ngx-phone-field

ngx-phone-field

ngx-phone-field is an Angular directive that provides international phone input with country flag dropdowns. It integrates with Angular forms, supporting both Reactive Forms and Template-Driven Forms.

Table of Contents

1. Features
2. Version Compatibility
3. Installation
   • Include Required Styles
4. Usage
   • Standalone Directive and Example with Reactive Forms
   • Standalone Directive and Example with Template-Driven Forms
5. Configuration Options
6. Instance Methods and Properties
   • Static Methods
   • Events
7. Loading The Utilities Script
8. Development
9. License

Features

• International phone input field with country code selection.
• Supports intl-tel-input functionalities such as number validation, formatting, and placeholder management.
• Works with both Reactive Forms and Template-Driven Forms.
• Customizable via configuration options.

Version Compatibility

ngx-phone-field Version	Supported Angular Versions
v3.x.x	Angular 19
v2.x.x	Angular 15 to Angular 18 (inclusive)
v1.x.x	Angular 10 to Angular 14 (inclusive)

Installation

npm install ngx-phone-field intl-tel-input

Include Required Styles

In order for the phone input field to render correctly with flags and dropdown styles, you need to include the required CSS file in your angular.json:

• Open your angular.json file.
• Add the intl-tel-input styles to the styles array in angular.json:

{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "src/styles.css",
              "node_modules/intl-tel-input/build/css/intlTelInput.css"
            ]
          }
        }
      }
    }
  }
}

Usage

ngxPhoneField directive returns the full intl-tel-input instance when the input changes. This gives the access to all the methods and properties available in the intl-tel-input API, providing full flexibility for advanced use cases.

Standalone directive and Example with Reactive Forms

import { Component } from '@angular/core';
import { FormGroup, FormControl, ReactiveFormsModule } from '@angular/forms';
import { NgxPhoneField } from 'ngx-phone-field';

@Component({
  selector: 'app-phone-form',
  standalone: true,
  template: `
    <form [formGroup]="phoneForm">
      <label for="phone">Phone Number</label>
      <input
        type="tel"
        id="phone"
        formControlName="phone"
        ngxPhoneField
        [ngxPhoneFieldParams]="params"
      />
    </form>
  `,
  imports: [ReactiveFormsModule, NgxPhoneField]
})
export class PhoneFormComponent {
  phoneForm = new FormGroup({
    phone: new FormControl(''),
  });

  params = {
    initialCountry: 'us',
    allowDropdown: true,
    formatAsYouType: true,
    // @ts-ignore
    loadUtilsOnInit: async () => import('intl-tel-input/utils'), // load utils script for formatting and validation
  };

  handleSubmit() {
    const phoneControlValue = this.phoneForm.get('phone').value;
    console.log(phoneControlValue); // Iti instance
  }
}

Standalone directive and Example with Template-Driven Forms

import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { NgxPhoneField } from 'ngx-phone-field';

@Component({
  selector: 'app-template-phone-form',
  standalone: true,
  template: `
    <form #phoneForm="ngForm">
      <label for="phone">Phone Number</label>
      <input
        type="tel"
        id="phone"
        name="phone"
        [(ngModel)]="phone"
        ngxPhoneField
        [ngxPhoneFieldParams]="params"
        required
      />
    </form>

    <button (click)="logInstance()">Log Instance</button>
  `,
  imports: [FormsModule, NgxPhoneField]
})
export class TemplatePhoneFormComponent {
  public phone: string = '';
  
  params = {
    initialCountry: 'us',
    allowDropdown: true,
    formatAsYouType: true,
    // @ts-ignore
    loadUtilsOnInit: async () => import('intl-tel-input/utils'), // load utils script for formatting and validation
  };

  logInstance() {
    console.log(this.phone) // Iti instance
  }
}

Configuration Options

You can pass various options to configure the behavior of the phone input field through ngxPhoneFieldParams. The ngxPhoneFieldParams input accepts a configuration object, which includes all the properties from intl-tel-input. You can refer to the full list of properties in the Initialisation Options section here or see them below: .

Option	Type	Default	Description
allowDropdown	Boolean	true	Whether or not to allow the dropdown. If disabled, the selected country is not clickable, and the flag appears on the right. If separateDialCode is enabled, allowDropdown is forced to true.
autoPlaceholder	String	"polite"	Set the input's placeholder to an example number for the selected country. You can specify the number type using placeholderNumberType. Requires the utils script to be loaded.
containerClass	String	""	Additional classes to add to the wrapper <div>.
countryOrder	Array	null	Specify the order of the country list using an array of ISO2 country codes. Any omitted countries will appear after the specified ones.
countrySearch	Boolean	true	Add a search input to the top of the dropdown to filter the displayed countries.
customPlaceholder	Function	null	Change the placeholder generated by autoPlaceholder. The function must return a string. Example: customPlaceholder: (placeholder, countryData) => "e.g. " + placeholder.
dropdownContainer	Node	null	Instead of placing the country dropdown markup next to the input, append it to the specified node (e.g., document.body). Useful when the input is inside a container with overflow: hidden.
excludeCountries	Array	[]	Display all countries except the ones specified in this array.
fixDropdownWidth	Boolean	true	Fix the dropdown width to match the input width.
formatAsYouType	Boolean	true	Automatically format the number as the user types. Requires the utils script to be loaded.
formatOnDisplay	Boolean	true	Format the input value during initialization and on setNumber. Requires the utils script to be loaded.
geoIpLookup	Function	null	Custom function for IP lookup services to get the user's location and return the relevant country code. Requires setting initialCountry to auto.
hiddenInput	Function	null	Allows creating hidden input fields within a form to store the full international number and country code. This requires the input to be inside a form and the utils script to be loaded.
i18n	Object	{}	Localize or customize the country names and other user interface text. You can import predefined translations or provide your own custom translations.
initialCountry	String	""	Set the initial country selection using the country code (e.g., "us" for the United States). Can also be set to "auto" for automatic IP-based country detection.
loadUtilsOnInit	String or () => Promise	""	URL to the utils.js script for formatting/validation. It can also be a function returning a promise. Example: { loadUtilsOnInit: () => import("intl-tel-input/utils") }.
nationalMode	Boolean	true	Format numbers in the national format rather than the international format. This applies to placeholder numbers and when displaying existing numbers.
onlyCountries	Array	[]	In the dropdown, display only the countries specified in this array.
placeholderNumberType	String	"MOBILE"	Set the number type for the placeholder (e.g., "FIXED_LINE").
showFlags	Boolean	true	Show or hide the country flags. If set to false, a globe icon will be displayed instead of the flags.
separateDialCode	Boolean	false	Display the selected country's dial code next to the input field. Automatically opens the country dropdown if the user types a new dial code.
strictMode	Boolean	false	As the user types, ignore irrelevant characters and cap the input to the maximum valid number length. Requires the utils script to be loaded.
useFullscreenPopup	Boolean	true (on mobile)	Show the country list as a fullscreen popup on mobile devices and as an inline dropdown on larger devices.
utilsScript	String or () => Promise	""	⚠️ Deprecated. Use loadUtilsOnInit instead.
validationNumberType	String	"MOBILE"	Set the number type to enforce during validation with isValidNumber and number length enforcement with strictMode.

Instance Methods and Properties

Once you initialize the ngxPhoneField, the directive returns an instance of intl-tel-input with the following methods and properties:

Method	Description
destroy()	Removes the plugin from the input and unbinds all event listeners.
getExtension()	Returns the extension from the current number. Requires the utils script to be loaded. Example: if the input value is "[phone] ext. 1234", this will return "1234".
getNumber(format?)	Gets the current number in the specified format. Defaults to E.164 format. Formats are available in intlTelInput.utils.numberFormat. Example: iti.getNumber(intlTelInput.utils.numberFormat.E164) returns a string like "[phone]". Requires utils script.
getNumberType()	Returns the type of the current number (fixed-line/mobile/toll-free, etc.). Requires the utils script to be loaded. Example: iti.getNumberType() returns an integer matched against intlTelInput.utils.numberType.
getSelectedCountryData()	Returns the country data for the currently selected country, e.g., { name: "Afghanistan", iso2: "af", dialCode: "93" }.
getValidationError()	Returns information about a validation error. Example: iti.getValidationError() returns an integer matched against intlTelInput.utils.validationError.
isValidNumber()	Returns true or false based on whether the current number is valid (based on length). It respects the validationNumberType option (set to "MOBILE" by default). Requires utils script.
isValidNumberPrecise()	Returns true or false for more precise validation using detailed matching rules for each country/area code. This is more accurate but requires the plugin to be up-to-date. Requires the utils script.
setCountry(countryCode)	Changes the selected country. Example: iti.setCountry("gb"). This method automatically updates when calling setNumber with a full international number.
setNumber(number)	Inserts a number into the input and updates the selected country accordingly. If formatOnDisplay is enabled, it formats the number based on nationalMode. Example: iti.setNumber("[phone]").
setPlaceholderNumberType(type)	Changes the placeholderNumberType option. Example: iti.setPlaceholderNumberType("FIXED_LINE").
setDisabled(isDisabled)	Sets the disabled attribute of both the input field and the selected country button. Example: iti.setDisabled(true).

Static Methods

Method	Description
getCountryData()	Retrieves the plugin's country data, which can be reused elsewhere or modified before initialization. Example: intlTelInput.getCountryData() returns an array of country objects.
getInstance(input)	After initializing the plugin, access the instance again by passing in the input element. Example: const iti = intlTelInput.getInstance(input); iti.isValidNumber();.
loadUtils()	Manually loads the utils.js script. Can be useful for enabling formatting/validation on demand. Returns a Promise that can be handled with .then(). Example: intlTelInput.loadUtils("/build/js/utils.js").

Events

Event	Description
countrychange	Triggered when the selected country is updated (e.g., user selects a country from the dropdown, types a new dial code, or setCountry is called). Example: input.addEventListener("countrychange", () => { iti.getSelectedCountryData(); });.
open:countrydropdown	Triggered when the user opens the dropdown.
close:countrydropdown	Triggered when the user closes the dropdown.

Loading The Utilities Script

Enabling formatting and validation for phone numbers requires the utils.js script. Make sure to include this in your project to fully enable these features. For more information, you can refer to the official documentation - Loading The Utilities Script section.

Development

If you want to contribute or modify the package, follow these steps:

• Fork the repository to your own GitHub account.
• Clone your forked repository locally:

git clone https://github.com/alex-mirankov/ngx-phone-field.git

• Run npm install to install dependencies.
• Run ng build ngx-phone-field to build the project.
• Run ng serve intl-tel-demo to run the demo project and see your changes in action (if applicable).
• Make changes to the codebase.
• Test your changes thoroughly before submitting.
• Create a pull request from your fork to the original repository.
• Pass the code review and ensure your changes meet the project's contribution guidelines.

License

This project is licensed under the MIT License. See the LICENSE file for more information.