ngx-mat-input-tel
v22.2.0
Published
Angular Material phone number input with country selection, international formatting, and validation.
Maintainers
Readme
ngx-mat-input-tel — Angular Material phone number input
ngx-mat-input-tel is an Angular Material phone number input for entering and validating international telephone numbers. It adds a flag dropdown to any input, detects the user's country, displays a relevant placeholder and provides formatting/validation methods.
Demo
- https://stackblitz.com/~/github.com/rbalet/ngx-mat-input-tel
Caution
This is a fork from the ngx-mat-intl-tel-input library whish is not maintained anymore.
Supports:
| Angular | x-mat-input-tel | | ------- | --------------------------- | | >= 22 | >= 22.1 (Signal form ready) | | >= 22 | >= 19.2.0 (Non Signal form) | | >= 18 | >= 19.2.0 | | >= 15 | < 19.2.0 |
- Validation with libphonenumber-js
Installation
Install This Library
$ npm i ngx-mat-input-tel@latest
Install Dependencies Optional
$ npm i libphonenumber-js@latest
Usage
Import
Add NgxMatInputTelComponent to your component file:
imports: [NgxMatInputTelComponent];Example
Refer to main app in this repository for working example.
Signal Form usage (Angular 22+):
<form [formRoot]="phoneSignalForm">
<ngx-mat-input-tel [formField]="phoneSignalForm.phone"></ngx-mat-input-tel>
</form><form #f="ngForm" [formGroup]="phoneForm">
<ngx-mat-input-tel
[preferredCountries]="['us', 'gb']"
[enablePlaceholder]="true"
[enableSearch]="true"
name="phone"
ariaDescribedBy="phoneInput"
formControlName="phone"
></ngx-mat-input-tel>
</form><form #f="ngForm" [formGroup]="phoneForm">
<ngx-mat-input-tel
[preferredCountries]="['US', 'GB']"
[enablePlaceholder]="true"
[enableSearch]="true"
name="phone"
autocomplete="tel"
(countryChanged)="yourComponentMethodToTreatyCountryChangedEvent($event)"
formControlName="phone"
></ngx-mat-input-tel>
</form>If you want to show the sample number for the country selected or errors, use mat-hint and mat-error as
<form #f="ngForm" [formGroup]="phoneForm">
<ngx-mat-input-tel
[preferredCountries]="['US', 'GB']"
[onlyCountries]="['US', 'GB', 'ES']"
[enablePlaceholder]="true"
name="phone"
autocomplete="tel"
formControlName="phone"
#phone
></ngx-mat-input-tel>
<mat-hint>e.g. {{phone.$selectedCountry().placeholder}}</mat-hint>
<mat-error *ngIf="f.form.controls['phone']?.errors?.required">Required Field</mat-error>
<mat-error *ngIf="f.form.controls['phone']?.errors?.validatePhoneNumber"
>Invalid Number</mat-error
>
<mat-error *ngIf="f.form.controls['phone']?.errors?.countryNotAllowed">
Country not allowed
</mat-error>
</form>Native input accessibility
Use inputId to link a label to the telephone input. required, ariaInvalid, and
ariaDescribedBy apply to that same native input:
<label for="contact-phone">Phone</label>
<ngx-mat-input-tel
inputId="contact-phone"
[formControl]="phoneControl"
required
[ariaInvalid]="phoneControl.invalid && phoneControl.touched"
ariaDescribedBy="phone-help"
></ngx-mat-input-tel>
<p id="phone-help">Include the country code.</p>Inside mat-form-field, its label targets inputId, and its hint/error IDs are combined
with ariaDescribedBy. Leave ariaInvalid unset to use the component's ErrorStateMatcher.
The generated ID now belongs to the native input rather than the component host.
Programmatic form writes update the display without emitting a user change. Writing null,
undefined, or '' clears the input.
Inputs
| Options | Type | Default | Description |
| ------------------ | -------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------- |
| ariaLabel | string | Select country | Aria label for the country selector button |
| ariaInvalid | boolean | 'true' | 'false' | null | null | Native aria-invalid; defaults to the component error state |
| ariaDescribedBy | string | null | null | Native description IDs, combined with Material hint/error IDs |
| autocomplete | off | tel | off | For input autocompletion |
| cssClass | string | undefined | If input custom class are needed |
| countriesName | Record<string, string> | COUNTRIES_NAME | For using different country names in the dropdown (Eg. Multilingual website) |
| defaultCountry | CountryCode | undefined | Default country code |
| enablePlaceholder | boolean | false | Input placeholder text, which adapts to the country selected. |
| enableSearch | boolean | false | Whether to display a search bar to help filter down the list of countries |
| format | string **** | default | Format of "as you type" input. Possible values: national, international, default |
| hideAreaCodes | boolean | false | Hide the Area codes in the country dropdown selection |
| inputId | string | Generated unique ID | ID of the native telephone input, used by labels |
| maxLength | number | 15 | max length of the input. |
| onlyCountries | string[] | [] | List of manually selected country abbreviations, which will appear in the dropdown. |
| placeholder | string | undefined | Placeholder for the input component. |
| preferredCountries | string[] | [] | List of country abbreviations, which will appear at the top. |
| resetOnChange | boolean | false | Reset input on country change |
| required | boolean | false | Native required state and aria-required |
| searchPlaceholder | string | Search ... | Placeholder for the search input |
| validation | isPossible | isValid | isValid | Change the validation type |
| separateDialCode | boolean | false | Whether to separate the dial code from the input Note: you'll have to manually add margin-left to your input |
Outputs
| Options | Type | Default | Description |
| -------------- | ----------------------- | ----------- | ----------------- |
| countryChanged | EventEmitter<Country> | undefined | On country change |
Css variable
| Name | Default | Explanation |
| -------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
| --ngxMatInputTel-opacity | 0 | If you wish both, the country flag and the placeholder to be shown by default |
| --ngxMatInputTel-selector-opacity | 0 | If you wish the country flag to be shown by default |
| --ngxMatInputTel-placeholder-opacity | 0 | If you wish the placeholder flag to be shown by default |
| --ngxMatInputTel-flag-display | inline-block | If you wish to hide the country flag |
| --ngxMatInputTel-menu-flag-display | inline-block | If you wish to hide the country flag inside the menu only |
| --ngxMatInputTel-gap | 32px | If you wish to change the gap between the flag and the input field (Only works with separateDialCode) |
Validator
Nonempty values must parse as valid phone numbers; unparseable values return
{ validatePhoneNumber: true }. Empty values remain optional unless Validators.required
is supplied. Validation does not change the control's touched state.
Manual validator usage
If you need to manually add the validator, use the factory:
| Name | Description | Example |
| -------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------- |
| ngxMatInputTelValidatorFactory | Validator factory for phone and country restriction | phoneControl.addValidators([ngxMatInputTelValidatorFactory(['US','GB'])]) |
Library Contributions
- Fork repo.
- Go to
./projects/ngx-mat-input-tel - Update
./src/libwith new functionality. - Update README.md
- Pull request.
Helpful commands
- Build lib:
$ npm run build_lib - Copy license and readme files:
$ npm run copy-files - Create package:
$ npm run npm_pack - Build lib and create package:
$ npm run package
Use locally
After building and creating package, you can use it locally too.
In your project run:
$ npm install --save {{path to your local '*.tgz' package file}}
Authors and acknowledgment
- maintainer Raphaël Balet
- Forked from ngx-mat-intl-tel-input
Contributors
Contributions are welcome! See our contribution notes.

