Registry / web-framework / intl-tel-input

intl-tel-input

library27.0.11jsnpmunverified

The `intl-tel-input` library is a robust JavaScript plugin designed for entering, formatting, and validating international telephone numbers. Currently at version 27.0.11, it maintains an active release cadence with frequent bug fixes and feature enhancements, including recent updates for React, Vue, and Svelte components, and fixes for TypeScript type resolution. Key differentiators include automatic country detection via IP lookup, placeholder examples for selected countries, keyboard navigation for the country dropdown, real-time number formatting, and comprehensive validation powered by Google's libphonenumber library. It provides high-resolution flag images, includes TypeScript definitions, and supports extensive customization through options, methods, events, and CSS variables for theming.

web-framework serialization http-networking observability

npm install intl-tel-input

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · INTL-TEL-INPUT

intl-tel-input

web-frameworkjavascriptv27.0.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

intlTelInput

✓ import intlTelInput from 'intl-tel-input';

✗ const intlTelInput = require('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.

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> */

Debug

Known issues

breakingFor 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' />`.

affects: >=27.0.0

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

affects: >=26.9.1

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

affects: >=1.0.0

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

affects: <27.0.8

Errors

Common errors & fixes

TypeError: iti.isValidNumber is not a function

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

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'

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';`.

Upgrade

Version history

27.0.11latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jackocnr/intl-tel-input ↗

packagehttps://www.npmjs.com/package/intl-tel-input ↗

homepagehttps://intl-tel-input.com ↗