International Telephone Input for Angular Material (mat-tel-input)

An Angular Material package 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.

Live Demo

Supports:

• Angular v21
• Angular Material v21
• ReactiveFormsModule
• FormsModule
• Validation with libphonenumber-js

Installation

Install This Library

npm i mat-tel-input@latest

Install Dependencies (Optional)

npm i libphonenumber-js@latest

Usage

Import

Add MatTelInput to your component's imports:

import { MatTelInput } from 'mat-tel-input';

@Component({
  imports: [MatTelInput],
  // ...
})
export class MyComponent {}

Examples

Reactive Forms

<mat-form-field appearance="outline">
  <mat-label>Phone</mat-label>
  <mat-tel-input [preferredCountries]="['us', 'tz']" enablePlaceholder enableSearch formControlName="phone"></mat-tel-input>
  <mat-error>Invalid phone</mat-error>
</mat-form-field>

Template-driven Forms

<mat-form-field appearance="fill">
  <mat-label>Phone</mat-label>
  <mat-tel-input [(ngModel)]="phone" [preferredCountries]="['us', 'gb']" enablePlaceholder enableSearch autocomplete="tel" (countryChanged)="onCountryChanged($event)"></mat-tel-input>
</mat-form-field>

Hints and Errors

<mat-form-field>
  <mat-label>Phone</mat-label>
  <mat-tel-input [preferredCountries]="['us', 'tz']" enablePlaceholder enableSearch formControlName="phone"></mat-tel-input>
  <mat-hint>e.g. {{ phone.selectedCountry.placeHolder }}</mat-hint>
  @if (f.form.controls['phone']?.errors?.required) {
  <mat-error>Required Field</mat-error>
  } @if (f.form.controls['phone']?.errors?.validatePhoneNumber) {
  <mat-error>Invalid Number</mat-error>
  }
</mat-form-field>

The label floats automatically — no need to set [floatLabel]="'always'".

Inputs

| Option | Type | Default | Description | | -------------------- | ------------------- | -------------------------- | ---------------------------------------------------------------------------- | | enablePlaceholder | boolean | false | Show an example phone number as placeholder, adapts to selected country. | | enableSearch | boolean | false | Show a search bar in the country dropdown. | | format | PhoneNumberFormat | 'default' | Format of "as you type" input: 'default', 'national', 'international'. | | placeholder | string | '' | Custom placeholder for the input. | | maxLength | string \| number | 15 | Max length of the phone input. | | onlyCountries | string[] | [] | Restrict the dropdown to these country ISO-2 codes. | | preferredCountries | string[] | [] | Country ISO-2 codes to show at the top of the dropdown. | | resetOnChange | boolean | false | Reset phone input when the selected country changes. | | searchPlaceholder | string | 'Search country or code' | Placeholder text for the country search input. | | autocomplete | 'off' \| 'tel' | 'off' | HTML autocomplete attribute on the input. | | cssClass | string | undefined | Additional CSS class applied to the phone input element. | | name | string | undefined | HTML name attribute on the input. |

Outputs

| Output | Type | Description | | ---------------- | ----------------------- | --------------------------------------------- | | countryChanged | EventEmitter<Country> | Emits the selected Country when it changes. |

Exports

The library exports the following for use in your application:

| Export | Type | Description | | ---------------------- | ---------- | -------------------------------------------------------------- | | MatTelInput | Component | The phone input component. | | matTelInputValidator | Function | Phone number validator for use with reactive forms. | | Country | Interface | Country model (name, iso2, dialCode, flagClass, etc.). | | PhoneNumberFormat | Type alias | 'default' \| 'national' \| 'international' |

CSS Custom Properties

All visual aspects of the component can be customized via CSS custom properties. Set these on the mat-tel-input element or any ancestor.

Component

| Property | Default | Description | | ------------------------------------- | -------------------------------------- | ------------------------------------------------ | | --mat-tel-input-opacity | 1 | Global opacity for the selector and placeholder. | | --mat-tel-input-selector-opacity | (inherits --mat-tel-input-opacity) | Country selector button opacity. | | --mat-tel-input-placeholder-opacity | (inherits --mat-tel-input-opacity) | Input placeholder opacity. | | --mat-tel-input-arrow-color | currentColor | Dropdown arrow color. | | --mat-tel-input-disabled-color | rgba(0,0,0,0.38) | Text color when disabled. |

Flag

| Property | Default | Description | | ------------------------------------ | -------------- | -------------------------------------------- | | --mat-tel-input-flag-display | inline-block | Set to none to hide the country flag. | | --mat-tel-input-flag-border-radius | 0 | Flag border radius (e.g. 2px for rounded). |

Dial Code

| Property | Default | Description | | ------------------------------------- | --------- | --------------------- | | --mat-tel-input-dial-code-color | inherit | Dial code text color. | | --mat-tel-input-dial-code-font-size | inherit | Dial code font size. |

Country Dropdown

| Property | Default | Description | | ------------------------------------------ | ------------------ | -------------------------------------- | | --mat-tel-input-dropdown-max-height | 400px | Max height of the country dropdown. | | --mat-tel-input-country-text-color | rgba(0,0,0,0.87) | Text color of country list items. | | --mat-tel-input-search-border-color | rgba(0,0,0,0.12) | Border color of the search input. | | --mat-tel-input-search-bg | #fff | Background of the search input. | | --mat-tel-input-search-color | inherit | Text color of the search input. | | --mat-tel-input-search-placeholder-color | rgba(0,0,0,0.6) | Placeholder color of the search input. |

Example: Custom Styling

mat-tel-input {
  --mat-tel-input-flag-border-radius: 2px;
  --mat-tel-input-arrow-color: #666;
  --mat-tel-input-dial-code-color: #1976d2;
}

Validator

The library exports its phone number validator so you can add it manually if needed:

import { matTelInputValidator } from 'mat-tel-input';

this.phoneControl.addValidators([matTelInputValidator]);

Library Contributions

• Fork repo.
• Go to ./libs/mat-tel-input
• Update ./src/lib with new functionality.
• Update README.md
• Pull request.

Helpful commands

• Build library: yarn nx build mat-tel-input
• Run tests: yarn nx test mat-tel-input
• Publish package: yarn publish

Authors and acknowledgment

• Maintainer Munir I Said
• Originally forked from ngx-mat-input-tel