{"id":11092,"library":"intl-tel-input","title":"intl-tel-input: International Telephone Input","description":"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.","status":"active","version":"27.0.11","language":"javascript","source_language":"en","source_url":"https://github.com/jackocnr/intl-tel-input","tags":["javascript","international","country","dial code","telephone","phone","mobile","input","flag","typescript"],"install":[{"cmd":"npm install intl-tel-input","lang":"bash","label":"npm"},{"cmd":"yarn add intl-tel-input","lang":"bash","label":"yarn"},{"cmd":"pnpm add intl-tel-input","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Main plugin function for initializing the input. For CommonJS environments, use `require`.","wrong":"const intlTelInput = require('intl-tel-input');","symbol":"intlTelInput","correct":"import intlTelInput from 'intl-tel-input';"},{"note":"TypeScript type definition for configuring the plugin's behavior.","symbol":"IntlTelInputOptions","correct":"import type { IntlTelInputOptions } from 'intl-tel-input';"},{"note":"TypeScript type for the country object, often returned by `getSelectedCountryData()` or in `countrychange` events.","symbol":"CountryData","correct":"import type { CountryData } from 'intl-tel-input';"}],"quickstart":{"code":"import intlTelInput from 'intl-tel-input';\nimport 'intl-tel-input/styles'; // Import default styles\n\ndocument.addEventListener('DOMContentLoaded', () => {\n  const inputElement = document.getElementById('phone-input') as HTMLInputElement | null;\n\n  if (inputElement) {\n    const iti = intlTelInput(inputElement, {\n      initialCountry: 'us',\n      separateDialCode: true,\n      preferredCountries: ['us', 'gb', 'ca'],\n      // `utilsScript` is crucial for validation and formatting functions\n      // It can be served locally or via a CDN.\n      utilsScript: 'https://cdn.jsdelivr.net/npm/intl-tel-input@27.0.11/build/js/utils.js',\n    });\n\n    inputElement.addEventListener('countrychange', () => {\n      const selectedCountryData = iti.getSelectedCountryData();\n      console.log('Country changed:', selectedCountryData);\n    });\n\n    document.getElementById('validate-btn')?.addEventListener('click', () => {\n      if (iti.isValidNumber()) {\n        console.log('Valid number:', iti.getNumber());\n        alert(`Valid number: ${iti.getNumber()}`);\n      } else {\n        const errorCode = iti.getValidationError();\n        console.log('Invalid number (error code):', errorCode);\n        alert(`Invalid number. Error code: ${errorCode}`);\n      }\n    });\n\n    console.log('intl-tel-input initialized and ready.', iti);\n  }\n});\n\n/*\nMinimal HTML to run this code:\n<input type=\"tel\" id=\"phone-input\">\n<button id=\"validate-btn\">Validate Number</button>\n*/","lang":"typescript","description":"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."},"warnings":[{"fix":"Migrate component usage from `<IntlTelInput initOptions={{ initialCountry: 'us' }} />` to `<IntlTelInput initialCountry='us' />`.","message":"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.","severity":"breaking","affected_versions":">=27.0.0"},{"fix":"Update any code relying on specific fields from `getSelectedCountryData()` or the `countrychange` event to only use the `name`, `iso2`, or `dialCode` properties.","message":"The structure of the data returned by `getSelectedCountryData()` and within the `countrychange` event has been simplified, exposing only `name`, `iso2`, and `dialCode` properties.","severity":"breaking","affected_versions":">=26.9.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<27.0.8"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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()) { ... } })`.","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.","error":"TypeError: iti.isValidNumber is not a function"},{"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.","cause":"The main `intl-tel-input` JavaScript library has not been correctly imported or included in your project.","error":"ReferenceError: intlTelInput is not defined"},{"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';`.","cause":"The module path for importing the library's CSS styles is incorrect or your bundler configuration is not set up to handle it.","error":"Failed to compile. Module not found: Error: Can't resolve 'intl-tel-input/styles'"}],"ecosystem":"npm"}