NgxMaterialIntlTelInput

https://github.com/juanjotorres90/ngx-material-intl-tel-input

Introducing an Angular library designed to streamline the input and validation of international telephone numbers. Integrates a searchable material select component for convenient country code selection. Moreover, it automatically detects the user's country, dynamically presenting a relevant placeholder for enhanced user experience. With built-in formatting and validation functionalities, this library ensures accuracy and consistency in handling telephone numbers across diverse global contexts.

Check out the Demo

Compatibility:

Validation with google-libphonenumber

| ngx-material-intl-tel-input | Angular |
| --------------------------- | ------- |
| 21.0.0 | 21 |
| 20.0.0 - 20.1.2 | 20 |
| 19.0.0 - 19.2.1 | 19 |
| 18.0.0 - 18.2.1 | 18 |
| 0.0.1 - 17.3.0 | 17 |

> Note: This package is completely different from ngx-intl-tel-input, ngx-mat-input-tel or intl-tel-input. It was built from scratch specifically for Angular Material and has no relation to those packages.

Installation

$ npm install ngx-material-intl-tel-input --save

Ensure to include provideAnimations() and provideHttpClient() in the providers array of your main.ts file to initialize your application with animations and auto getting country code capabilities. Refer to the Angular Docs provideAnimations and provideHttpClient for detailed instructions.

Additionally, it's essential to incorporate an Angular Material theme by importing the necessary CSS for styling. Please consult the Angular Material Theming guide for instructions on how to set up the theme.

Usage

$3

Include the NgxMaterialIntlTelInputComponent in the imports array of the standalone component where you intend to utilize it.

``typescript
imports: [NgxMaterialIntlTelInputComponent];
`

Example

`html







`

Options

| Options | Type | Default | Description |
| ------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| fieldControl | FormControl | FormControl('') | Form control required to retrieve the value. |
| fieldControlName | string | '' | Form control name to assign the control from a FormGroup. |
| required | boolean | false | Telephone field input required. |
| disabled | boolean | false | Telephone field input disabled. |
| appearance | 'fill' \| 'outline' | fill | Material form field appearance. |
| autoIpLookup | boolean | true | Sets initial country code based on user's ip. |
| autoSelectCountry | boolean | true | Enables or disables auto selecting a country on initialization. |
| autoSelectedCountry | CountryISO \| string | '' | Sets the country to be auto selected. |
| numberValidation | boolean | true | Enables or disables phone number validation. |
| enableSearch | boolean | true | Enables or disables country search. |
| includeDialCode | boolean | false | Includes the dial code in the phone number input. |
| emojiFlags | boolean | false | Use standard emoji icons for the country flags. |
| hidePhoneIcon | boolean | false | Hides phone icon. |
| preferredCountries | (CountryISO \| string)[] | [] | Shows the specified countries on top of the list. |
| visibleCountries | (CountryISO \| string)[] | [] | Shows only the specified countries. |
| excludedCountries | (CountryISO \| string)[] | [] | Exclude the specified countries from the list. |
| enablePlaceholder | boolean | true | Input placeholder text for every country national number. |
| iconMakeCall | boolean | true | Click on phone icon to trigger call action. |
| initialValue | string | '' | Sets initial telephone number value |
| useMask | boolean | false | Use mask for phone number input. |
| forceSelectedCountryCode | boolean | false | If useMask is active it forces the selected country code to be displayed |
| showMaskPlaceholder | boolean | false | If useMask is active it shows the placeholder for the mask |
| outputNumberFormat | PhoneNumberFormat | PhoneNumberFormat.INTERNATIONAL | Sets the output number format to INTERNATIONAL, E164, or RFC3966 format |
| enableInputMaxLength | boolean | true | Enables or disables the input max length. |
| localizeCountryNames | boolean | false | Opt-in to locale-aware country names. |
| textLabels | TextLabels | {mainLabel: 'Phone number', codePlaceholder: 'Code', searchPlaceholderLabel: 'Search', noEntriesFoundLabel: 'No countries found', nationalNumberLabel: 'Number', hintLabel: 'Select country and type your phone number', invalidNumberError: 'Number is not valid', requiredError: 'This field is required'} | Overrides all component text labels |
| mainLabel | string | '' | Sets the main label of the input field. It overrides the textLabels.mainLabel. |

Events

| Event | Type | Default | Description |
| ------------------ | -------- | ------- | -------------------------------------------------------------------- |
| currentValue | string | '' | Full phone number value emitted when the value of the input changes. |
| currentCountryCode | string | '' | Country code value emitted when the value of the input changes. |
| currentCountryISO | string | '' | Country ISO value emitted when the value of the input changes. |

CSS Custom Properties Reference

🎨 Component Styling Variables

$3

- --mat-filled-tel-form-outline-width: Outline width (default: 1px)
- --mat-filled-tel-form-outline-color: Border color (default: #d8d8d8)
- --mat-filled-tel-form-background: Background color (default: #fbfbfb)
- --mat-filled-tel-form-container-shape: Border radius (default: 8px)

$3

- --mat-filled-tel-form-focus-outline-color: Focus border color (default: rgb(32, 159, 252))
- --mat-filled-tel-form-focus-background: Focus background (default: #fff)

$3

- --mat-filled-tel-form-hover-background: Hover background (default: #f5f5f5)
- --mat-outline-tel-form-hover-background: Outline variant hover background (default: #f5f5f5)

📱 Input Field Customization

$3

- --mat-outline-tel-form-background: Outline variant background (default: #fbfbfb)
- --mat-tel-form-placeholder-color: Input placeholder color (default: #ccc)
- --mat-tel-form-icon-color: Action icon color (default: #909090)

$3

- --mat-outlined-tel-form-container-shape: Outline field border radius (default: Material system variable)
- --mat-outlined-text-field-container-shape: Text field border radius (default: Material system variable)

🔍 Validation & Feedback

- --mat-tel-form-hint-color: Hint text color (default: #b2b2b2)
- --mat-tel-form-error-color: Error message color (default: Material system error)
- --mat-sys-error: Material system error fallback (default: #f44336)

🖌️ Theme Integration

- --mat-theme-primary: Primary theme color (default: rgb(32, 159, 252))
- --mat-theme-error: Error state color (default: #f44336)
- --mat-sys-corner-extra-small: Material system small corner radius

Example Configuration

`css
:root {
/ Container Customization /
--mat-filled-tel-form-background: #f8f9fa;
--mat-filled-tel-form-container-shape: 6px;

/ Theme Colors /
--mat-theme-primary: #2a7de1;
--mat-tel-form-error-color: #dc3545;

/ Input Styling /
--mat-tel-form-placeholder-color: #a0aec0;
}
`

Localization

The country selector now supports locale-aware display names and accent-insensitive search. Enable localization per instance with [localizeCountryNames]="true". When disabled (default) the component keeps the original English dataset.

If the browser exposes Intl.DisplayNames, the component will resolve translated labels for the active LOCALE_ID. You can override specific entries through the COUNTRY_NAME_OVERRIDES token:

`ts
import { COUNTRY_NAME_OVERRIDES, CountryNameOverrides } from 'ngx-material-intl-tel-input';

const spanishCountryOverrides: CountryNameOverrides = {
US: 'Estados Unidos de América',
MX: 'Estados Unidos Mexicanos'
};

bootstrapApplication(AppComponent, {
providers: [
provideAnimations(),
{ provide: LOCALE_ID, useValue: 'es-ES' },
{
provide: COUNTRY_NAME_OVERRIDES,
useValue: spanishCountryOverrides
}
]
});
``

Contributors

Thanks goes to these wonderful people:

Juanjo Torres 🎨 💻 📖 🤔 💬 🚇 💡 🚧 👀 ⚠️

Rafa Hernández 💻 🤔 💬 🚇 🚧 👀

Glen Hollingworth 💻 🤔 💬 💡 🚧 👀

EphraimHaber 💻 🤔 💬 💡 🚧 👀

Rant 💻 🤔 💬 💡 🚧 👀

Jean Talar 💻 🤔 💬 💡 🚧 👀

This project follows the all-contributors specification. Contributions of any kind are welcome!