mat-tel-input
Version:
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.
199 lines (146 loc) • 9.22 kB
Markdown
# 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.
[](https://www.npmjs.com/package/mat-tel-input)
**[Live Demo](https://mattelinput.muneersahel.com)**
**Supports:**
- Angular v21
- Angular Material v21
- ReactiveFormsModule
- FormsModule
- Validation with [libphonenumber-js](https://github.com/catamphetamine/libphonenumber-js)
## Installation
### Install This Library
```sh
npm i mat-tel-input@latest
```
### Install Dependencies _(Optional)_
```sh
npm i libphonenumber-js@latest
```
## Usage
### Import
Add `MatTelInput` to your component's `imports`:
```ts
import { MatTelInput } from 'mat-tel-input';
@Component({
imports: [MatTelInput],
// ...
})
export class MyComponent {}
```
## Examples
### Reactive Forms
```html
<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
```html
<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
```html
<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
```css
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:
```ts
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](https://github.com/Muneersahel)
- Originally forked from [ngx-mat-input-tel](https://github.com/rbalet/ngx-mat-input-tel)