intl-tel-input: International Telephone Input

Common errors

• TypeError: iti.isValidNumber is not a function

  cause The `utils.js` script, which provides number validation and formatting functions, has not been loaded or has not finished loading before `isValidNumber()` was called.
  fix Call `intlTelInputInstance.loadUtils('/path/to/utils.js')` and ensure its promise resolves before invoking validation methods. For example: `iti.loadUtils('...').then(() => { if (iti.isValidNumber()) { ... } })`.

• ReferenceError: intlTelInput is not defined

  cause The main `intl-tel-input` JavaScript library has not been correctly imported or included in your project.
  fix For modern JavaScript modules, use `import intlTelInput from 'intl-tel-input';`. For CommonJS, use `const intlTelInput = require('intl-tel-input');`. For global usage, ensure the script tag for `intl-tel-input.min.js` is present in your HTML before your custom script.

• Failed to compile. Module not found: Error: Can't resolve 'intl-tel-input/styles'

  cause The module path for importing the library's CSS styles is incorrect or your bundler configuration is not set up to handle it.
  fix Ensure you are using `import 'intl-tel-input/styles';` (recommended since v27.0.8). If this still fails or you're on an older version, try `import 'intl-tel-input/build/css/intlTelInput.css';`.

Warnings

• breaking For React, Vue, Angular, and Svelte components, plugin options are now passed as individual props directly to the component instead of being nested within an `initOptions` object.
  Fix: Migrate component usage from `<IntlTelInput initOptions={{ initialCountry: 'us' }} />` to `<IntlTelInput initialCountry='us' />`.
• breaking The structure of the data returned by `getSelectedCountryData()` and within the `countrychange` event has been simplified, exposing only `name`, `iso2`, and `dialCode` properties.
  Fix: Update any code relying on specific fields from `getSelectedCountryData()` or the `countrychange` event to only use the `name`, `iso2`, or `dialCode` properties.
• gotcha The full validation and formatting features (e.g., `isValidNumber()`, `getNumber()`, `getNumberType()`) rely on a separate `utils.js` script (powered by Google's libphonenumber). This script must be explicitly loaded via `intlTelInput.loadUtils(path)` after the main plugin is initialized.
  Fix: Ensure `iti.loadUtils('/path/to/utils.js')` is called and its promise resolves before attempting to use validation-related methods. The `utils.js` file is typically found in `node_modules/intl-tel-input/build/js/utils.js` or available via CDN.
• gotcha Older versions (prior to v27.0.8) might experience issues with the dropdown separating from the input when placed inside `display: flex` or `display: grid` containers, or incorrect dropdown width when `enableSeparateDialCode` is true.
  Fix: Update to version 27.0.8 or newer. If upgrading is not possible, review custom CSS, especially `padding-left` properties and flexbox/grid overrides, for potential conflicts.

Install

• npm install intl-tel-input npm
• yarn add intl-tel-input yarn
• pnpm add intl-tel-input pnpm

Imports

• intlTelInput
  wrong:

  const intlTelInput = require('intl-tel-input');

  correct:

  import intlTelInput from 'intl-tel-input';

  Main plugin function for initializing the input. For CommonJS environments, use `require`.
• IntlTelInputOptions

  import type { IntlTelInputOptions } from 'intl-tel-input';

  TypeScript type definition for configuring the plugin's behavior.
• CountryData

  import type { CountryData } from 'intl-tel-input';

  TypeScript type for the country object, often returned by `getSelectedCountryData()` or in `countrychange` events.

Quickstart

This quickstart initializes the international telephone input plugin on an HTML input element. It configures basic options like initial and preferred countries, loads the essential utility script for validation, and demonstrates how to handle country changes and validate the entered phone number.

import intlTelInput from 'intl-tel-input';
import 'intl-tel-input/styles'; // Import default styles

document.addEventListener('DOMContentLoaded', () => {
  const inputElement = document.getElementById('phone-input') as HTMLInputElement | null;

  if (inputElement) {
    const iti = intlTelInput(inputElement, {
      initialCountry: 'us',
      separateDialCode: true,
      preferredCountries: ['us', 'gb', 'ca'],
      // `utilsScript` is crucial for validation and formatting functions
      // It can be served locally or via a CDN.
      utilsScript: 'https://cdn.jsdelivr.net/npm/intl-tel-input@27.0.11/build/js/utils.js',
    });

    inputElement.addEventListener('countrychange', () => {
      const selectedCountryData = iti.getSelectedCountryData();
      console.log('Country changed:', selectedCountryData);
    });

    document.getElementById('validate-btn')?.addEventListener('click', () => {
      if (iti.isValidNumber()) {
        console.log('Valid number:', iti.getNumber());
        alert(`Valid number: ${iti.getNumber()}`);
      } else {
        const errorCode = iti.getValidationError();
        console.log('Invalid number (error code):', errorCode);
        alert(`Invalid number. Error code: ${errorCode}`);
      }
    });

    console.log('intl-tel-input initialized and ready.', iti);
  }
});

/*
Minimal HTML to run this code:
<input type="tel" id="phone-input">
<button id="validate-btn">Validate Number</button>
*/