Awesome

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

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: .

Instance Methods and Properties

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

Static Methods

Events

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.