ngx-material-intl-tel-input

[![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors) [![npm version](https://img.shields.io/npm/v/ngx-material-intl-tel-input.svg?style=flat-square)](https://www.npmjs.com/package/ngx-material-intl-tel-input) [![npm downloads total](https://img.shields.io/npm/dt/ngx-material-intl-tel-input.svg?style=flat-square)](https://www.npmjs.com/package/ngx-material-intl-tel-input) [![npm downloads monthly](https://img.shields.io/npm/dm/ngx-material-intl-tel-input.svg?style=flat-square)](https://www.npmjs.com/package/ngx-material-intl-tel-input) # NgxMaterialIntlTelInput [https://github.com/juanjotorres90/ngx-material-intl-tel-input](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](https://juanjotorres.net/projects/ngx-material-intl-tel-input) <img width="490" alt="preview" src="https://github.com/juanjotorres90/ngx-material-intl-tel-input/assets/49198908/d0714418-c1bf-45af-a98c-8c54f3eb9144"> **Compatibility:** Validation with [google-libphonenumber](https://github.com/google/libphonenumber) | ngx-material-intl-tel-input | Angular | | --------------------------- | ------- | | 20.0.0 - 20.1.1 | 20 | | 19.0.0 - 19.2.1 | 19 | | 18.0.0 - 18.2.1 | 18 | | 0.0.1 - 17.3.0 | 17 | ## 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](https://angular.dev/api/platform-browser/animations/provideAnimations#) and [provideHttpClient](https://angular.dev/api/common/http/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](https://material.angular.io/guide/theming) for instructions on how to set up the theme. ## Usage ### Import Include the NgxMaterialIntlTelInputComponent in the imports array of the standalone component where you intend to utilize it. ```typescript imports: [NgxMaterialIntlTelInputComponent]; ``` ## Example ```html <form [formGroup]="formGroup"> <ngx-material-intl-tel-input [fieldControl]="control" [required]="true" [autoIpLookup]="false"> </ngx-material-intl-tel-input> </form> ``` ## 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. | | 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 ### Container Styles - `--mdc-filled-tel-form-outline-width`: Outline width (`default: 1px`) - `--mdc-filled-tel-form-outline-color`: Border color (`default: #d8d8d8`) - `--mdc-filled-tel-form-background`: Background color (`default: #fbfbfb`) - `--mdc-filled-tel-form-container-shape`: Border radius (`default: 8px`) ### Focus States - `--mdc-filled-tel-form-focus-outline-color`: Focus border color (`default: rgb(32, 159, 252)`) - `--mdc-filled-tel-form-focus-background`: Focus background (`default: #fff`) ### Hover States - `--mdc-filled-tel-form-hover-background`: Hover background (`default: #f5f5f5`) - `--mdc-outline-tel-form-hover-background`: Outline variant hover background (`default: #f5f5f5`) ## 📱 Input Field Customization ### Appearance - `--mdc-outline-tel-form-background`: Outline variant background (`default: #fbfbfb`) - `--mdc-tel-form-placeholder-color`: Input placeholder color (`default: #ccc`) - `--mdc-tel-form-icon-color`: Action icon color (`default: #909090`) ### Shape Customization - `--mdc-outlined-tel-form-container-shape`: Outline field border radius (`default: Material system variable`) - `--mdc-outlined-text-field-container-shape`: Text field border radius (`default: Material system variable`) ## 🔍 Validation & Feedback - `--mdc-tel-form-hint-color`: Hint text color (`default: #b2b2b2`) - `--mdc-tel-form-error-color`: Error message color (`default: Material system error`) - `--mat-sys-error`: Material system error fallback (`default: #f44336`) ## 🖌️ Theme Integration - `--mdc-theme-primary`: Primary theme color (`default: rgb(32, 159, 252)`) - `--mdc-theme-error`: Error state color (`default: #f44336`) - `--mat-sys-corner-extra-small`: Material system small corner radius ## Example Configuration ```css :root { /* Container Customization */ --mdc-filled-tel-form-background: #f8f9fa; --mdc-filled-tel-form-container-shape: 6px; /* Theme Colors */ --mdc-theme-primary: #2a7de1; --mdc-tel-form-error-color: #dc3545; /* Input Styling */ --mdc-tel-form-placeholder-color: #a0aec0; } ``` ## Contributors Thanks goes to these wonderful people:    <table> <tr> <td align="center"><a href="https://github.com/juanjotorres90"><img src="https://avatars3.githubusercontent.com/u/49198908?v=4?s=100" width="100px;" alt=""/> Juanjo Torres</a> <a href="#design-juanjotorres90" title="Design">🎨</a> <a href="https://github.com/juanjotorres90/ngx-material-intl-tel-input/commits?author=juanjotorres90" title="Code">💻</a> <a href="https://github.com/juanjotorres90/ngx-material-intl-tel-input/commits?author=juanjotorres90" title="Documentation">📖</a> <a href="#ideas-juanjotorres90" title="Ideas, Planning, & Feedback">🤔</a> <a href="#question-juanjotorres90" title="Answering Questions">💬</a> <a href="#infra-juanjotorres90" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#example-juanjotorres90" title="Examples">💡</a> <a href="#maintenance-juanjotorres90" title="Maintenance">🚧</a> <a href="https://github.com/juanjotorres90/ngx-material-intl-tel-input/pulls?q=is%3Apr+reviewed-by%3Ajuanjotorres90" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/juanjotorres90/ngx-material-intl-tel-input/commits?author=juanjotorres90" title="Tests">⚠️</a></td> <td align="center"><a href="https://github.com/whegar"><img src="https://avatars3.githubusercontent.com/u/5524772?v=4?s=100" width="100px;" alt=""/> Rafa Hernández</a> <a href="https://github.com/juanjotorres90/ngx-material-intl-tel-input/commits?author=whegar" title="Code">💻</a> <a href="#ideas-whegar" title="Ideas, Planning, & Feedback">🤔</a> <a href="#question-whegar" title="Answering Questions">💬</a> <a href="#infra-whegar" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#maintenance-whegar" title="Maintenance">🚧</a> <a href="https://github.com/juanjotorres90/ngx-material-intl-tel-input/pulls?q=is%3Apr+reviewed-by%whegar" title="Reviewed Pull Requests">👀</a></td> <td align="center"><a href="https://github.com/ghollingworthh"><img src="https://avatars.githubusercontent.com/u/26550815?v=4?s=100" width="100px;" alt=""/> Glen Hollingworth</a> <a href="https://github.com/juanjotorres90/ngx-material-intl-tel-input/commits?author=ghollingworthh" title="Code">💻</a> <a href="#ideas-ghollingworthh" title="Ideas, Planning, & Feedback">🤔</a> <a href="#question-ghollingworthh" title="Answering Questions">💬</a> <a href="#example-ghollingworthh" title="Examples">💡</a> <a href="#maintenance-ghollingworthh" title="Maintenance">🚧</a> <a href="https://github.com/juanjotorres90/ngx-material-intl-tel-input/pulls?q=is%3Apr+reviewed-by%ghollingworthh" title="Reviewed Pull Requests">👀</a></td> <td align="center"><a href="https://github.com/EphraimHaber"><img src="https://avatars.githubusercontent.com/u/61934858?v=4?s=100" width="100px;" alt=""/> EphraimHaber</a> <a href="https://github.com/juanjotorres90/ngx-material-intl-tel-input/commits?author=EphraimHaber" title="Code">💻</a> <a href="#ideas-EphraimHaber" title="Ideas, Planning, & Feedback">🤔</a> <a href="#question-EphraimHaber" title="Answering Questions">💬</a> <a href="#example-EphraimHaber" title="Examples">💡</a> <a href="#maintenance-EphraimHaber" title="Maintenance">🚧</a> <a href="https://github.com/juanjotorres90/ngx-material-intl-tel-input/pulls?q=is%3Apr+reviewed-by%EphraimHaber" title="Reviewed Pull Requests">👀</a></td> <td align="center"><a href="https://github.com/Kamma31"><img src="https://avatars.githubusercontent.com/u/50776388?v=4?s=100" width="100px;" alt=""/> Rant</a> <a href="https://github.com/juanjotorres90/ngx-material-intl-tel-input/commits?author=Kamma31" title="Code">💻</a> <a href="#ideas-Kamma31" title="Ideas, Planning, & Feedback">🤔</a> <a href="#question-Kamma31" title="Answering Questions">💬</a> <a href="#example-Kamma31" title="Examples">💡</a> <a href="#maintenance-Kamma31" title="Maintenance">🚧</a> <a href="https://github.com/juanjotorres90/ngx-material-intl-tel-input/pulls?q=is%3Apr+reviewed-by%Kamma31" title="Reviewed Pull Requests">👀</a></td> </table>    This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome! [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/juanjotorres)