Initialisation Options

An array of iso2 country codes that is used to order the country dropdown. Any omitted countries will appear after those specified, in alphabetical order, e.g. setting countryOrder to ["jp", "kr"] will result in the list: Japan, South Korea, Afghanistan, Albania, Algeria, etc. See what this looks like in the Playground. Note: this replaces the legacy preferredCountries option (now removed).

An array of iso2 country codes to exclude from the country dropdown e.g. ["gb", "us"]. Play with this option in the Playground. Also see: onlyCountries option.

Set the initial country selection by specifying its country code, e.g. "us" for the United States. (Be careful not to do this unless you are sure of the user’s country, as it can lead to tricky issues if set incorrectly and the user auto-fills their national number and submits the form without checking - in certain cases, this can pass validation and you can end up storing a number with the wrong dial code). You can also set initialCountry to "auto", which will look up the user’s country based on their IP address (requires the geoIpLookup option - see example). Note: however you use initialCountry, it will not update the country selection if the input already contains a number with an international dial code. View the plugin with this set to "de" (Germany) in the Playground.

When setting initialCountry to "auto", you must use this option to specify a custom function that calls an IP lookup service to get the user’s location and then invokes the success callback with the relevant country code. Also note that when instantiating the plugin, a Promise object is returned under the promise instance property, so you can do something like iti.promise.then(...) to know when initialisation requests like this have completed.

Here is an example using the ipapi service:

intlTelInput(input, {
  initialCountry: "auto",
  geoIpLookup: (success, failure) => {
    fetch("https://ipapi.co/json")
      .then((res) => res.json())
      .then((data) => success(data.country_code))
      .catch(() => failure());
  }
});

Note that the failure callback must be called in the event of an error, hence the use of catch() in this example. Tip: store the result in a cookie to avoid repeat lookups!

In the dropdown, display only the countries you specify here, using their iso2 codes e.g. ["fr", "de", "es"]. Try the plugin with this option set to only European countries in the Playground (and open the country dropdown). Also see: excludeCountries option.

Whether or not to allow the dropdown. If disabled, there is no dropdown arrow, and the selected country is not clickable. Also, if showFlags is enabled, we display the selected flag on the right instead, because it is just a marker of state. Note that if separateDialCode is enabled, allowDropdown is forced to true as the dropdown is required when the user types “+” in this case. Try the plugin with allowDropdown disabled in the Playground.

Additional class(es) to add to the (injected) wrapper <div class="iti">.

Add a search input to the top of the dropdown, so users can filter the displayed countries. View the plugin with this disabled in the Playground.

Expects a node, e.g. document.body. Instead of putting the country dropdown markup next to the input, append it to the specified node, and it will then be positioned next to the input using JavaScript (using position: fixed). This is useful when the input is inside a container with overflow: hidden. Note that the positioning is broken by scrolling, so the dropdown will automatically close on the window scroll event. This also applies to the fullscreen popup.

Fix the dropdown width to the input width (rather than being as wide as the longest country name). Try the plugin with this disabled in the Playground.

Display the selected country’s international dial code next to the input, so it looks like it’s part of the typed number. This makes it clear to the user which dial code is currently selected and that they are entering their number in international format. In the case that the user tries to type a new dial code (as well), we automatically open the country dropdown and put the newly typed dial code in the search input instead. So if they type +54, then Argentina will be highlighted in the dropdown, and they can simply press Enter to select it, updating the displayed dial code (this feature requires allowDropdown and countrySearch to be enabled). Try the plugin with this enabled (and initialCountry=“gb”) in the Playground. Note: previously named showSelectedDialCode.

Set this to false to hide the flags, e.g. for political reasons. Instead, it will show a generic globe icon. Try the plugin with this disabled in the Playground (and open country dropdown).

Control when the country list appears as a fullscreen popup vs an inline dropdown. By default, it will appear as a fullscreen popup on mobile devices (based on user-agent and screen width), to make better use of the limited space (similar to how a native <select> works), and as an inline dropdown on larger devices/screens. Play with this option in the Playground.

Set the input’s placeholder to an example number for the selected country, and update it if the country changes. You can specify the number type using the placeholderNumberType option. By default, it is set to "polite", which means it will only set the placeholder if the input doesn’t already have one. You can also set it to "aggressive", which will replace any existing placeholder, or "off". Requires the utils script to be loaded. Play with this option on an input that contains a placeholder in the Playground.

Change the placeholder generated by autoPlaceholder. Must return a string.

intlTelInput(input, {
  customPlaceholder: (selectedCountryPlaceholder, selectedCountryData) => "e.g. " + selectedCountryPlaceholder,
});

Specify one of the keys from the enum intlTelInput.utils.numberType (e.g. "FIXED_LINE") to set the number type to use for the generated placeholder numbers. Play with this option in the Playground.

Automatically format the number as the user types. This feature will be disabled if the user types their own formatting characters. Requires the utils script to be loaded. Try the plugin with this disabled in the Playground. Note: previously named autoFormat.

Format the input value (according to the nationalMode option) during initialisation, when a new country is selected, on setNumber and on setCountry. Requires the utils script to be loaded. Try toggling this option on/off on an input containing a number in the Playground.

Format numbers in the national format, rather than the international format. This applies to placeholder numbers and when displaying users’ existing numbers. Note that it’s fine for users to type their numbers in national format - as long as they have selected the right country, you can use getNumber to extract a full international number. It is recommended to leave this option enabled to encourage users to enter their numbers in national format, as this is usually more familiar to them, and so it creates a better user experience. Play with this option in the Playground.

As the user types in the input, ignore any irrelevant characters. The user can only enter numeric characters and an optional plus at the beginning. Cap the length at the maximum valid number length (this respects allowedNumberTypes). Requires the utils script to be loaded. Try the plugin with this enabled (and initialCountry=“us”) in the Playground.

Specify an array of the keys from the enum intlTelInput.utils.numberType to set the number type(s) to enforce during validation, as well as the number length to enforce with strictMode. Set it to null to not enforce any particular type. By default, it’s set to ["MOBILE", "FIXED_LINE"] so isValidNumber (etc) will only return true for those kinds of numbers. Alternatively, you could set it to simply ["MOBILE"] if you only wanted to accept mobile numbers as valid. Play with this option in the Playground. Note: previously named validationNumberTypes.

Whether or not the validation methods return true for numbers containing extensions, e.g. “+1 702 123-1234 ext. 1234”. Try toggling this option on/off on a number with an extension in the Playground.

Whether or not the validation methods return true for numbers containing phonewords, e.g. “+1 702 FLOWERS”. Play with this option in the Playground.

The locale to pass to Intl.DisplayNames to generate the country names. Should adhere to the BCP 47 standard, e.g. "zh", or "zh-Hans". For translating the other UI strings, like the country search placeholder, see i18n option. View the plugin with countryNameLocale set to "zh", and i18n set to the provided ZH user interface translations in the Playground (and open the country dropdown).

There are two aspects to the internationalisation of this plugin. The first is the country names, which are translated automatically using the native Intl.DisplayNames - just specify the locale you want using the countryNameLocale option. The second is the user interface strings (including the country search placeholder, search empty state, and various other strings for screen readers). We provide translations for these in over 40 languages - simply import the language module you need and pass it to the plugin using the i18n option (see option 1 below). You can also override one or more individual keys this way. Alternatively, you can provide your own custom translations (see option 2 below). If providing your own, please see the required UI strings listed below. See example. If we don’t currently support a language you need, it’s easy to contribute this yourself - you only need to provide a handful of UI translation strings. View the plugin with countryNameLocale set to "zh", and i18n set to the provided ZH user interface translations in the Playground (and open the country dropdown). Note: previously named localizedCountries.

Option 1: import one of the provided translation modules

import { fr } from "intl-tel-input/i18n";

intlTelInput(input, {
  i18n: fr,
});

// or to override one or more keys, you could do something like this
intlTelInput(input, {
  i18n: {
    ...fr,
    searchPlaceholder: "Recherche de pays",
    // or override a specific country name
    us: "United States",
  },
});

Option 2: define your own custom translations

intlTelInput(input, {
  i18n: {
    // Aria label for the selected country element, when there is a country selected
    selectedCountryAriaLabel: "Change country, selected ${countryName} (${dialCode})",
    // Aria label and title text for the selected country element, when no country is selected
    noCountrySelected: "Select country",
    // Aria label for the country list element
    countryListAriaLabel: "List of countries",
    // Placeholder for the search input in the dropdown
    searchPlaceholder: "Search",
    // Aria label for the clear search button
    clearSearchAriaLabel: "Clear search",
    // Visible text for when the search produces no results
    searchEmptyState: "No results found",
    // Screen reader summary of search results
    searchSummaryAria(count) {
      if (count === 0) return "No results found";
      if (count === 1) return "1 result found";
      return `${count} results found`;
    }
  }
});

Allows the creation of hidden input fields within a form, which, on submit, get populated with (1) the full international telephone number and (2) the selected country code. It accepts a function that receives the name of the main telephone input as an argument. This function should return an object with phone and (optionally) country properties to specify the names of the hidden inputs for the phone number and country code, respectively. This is useful for old-fashioned, page-load form submissions to ensure the full international number and country code are captured, especially when nationalMode is enabled. See example.

*Note: This feature requires the input to be inside a <form> element, as it listens for the submit event on the closest form element. Also note that since this uses getNumber internally, firstly it requires the utils script to be loaded, and secondly, it expects a valid number and so will only work correctly if you have used isValidNumber to validate the number before allowing the form submit to go through.

intlTelInput(input, {
  hiddenInput: (telInputName) => ({
    phone: "phone_full",
    country: "country_code"
  }),
});

This will generate the following (hidden) elements, which will be automatically populated on submit:

<input type="hidden" name="phone_full">
<input type="hidden" name="country_code">

This is one way to lazy load the included utils.js (to enable formatting/validation, etc) - see Loading The Utilities Script for more options.

The loadUtils option takes a function that returns a Promise resolving to the utils module. You can import the utils module in different ways (examples below): (A) from a CDN, (B) from your own hosted version of utils.js, or © if you use a bundler like Webpack, Vite or Parcel, you can import it directly from the package. Play with this option in the Playground. Note: this replaces the utilsScript option (now removed).

// (A) import utils module from a CDN
intlTelInput(htmlInputElement, {
  loadUtils: () => import("https://cdn.jsdelivr.net/npm/intl-tel-input@26.0.6/build/js/utils.js"),
});

// (B) import utils module from your own hosted version of utils.js
intlTelInput(htmlInputElement, {
  loadUtils: () => import("/path/to/utils.js"),
});

// (C) with a bundler, you can import the utils module directly from the package
intlTelInput(htmlInputElement, {
  loadUtils: () => import("intl-tel-input/utils"),
});

The module is only loaded when you initialise the plugin, and additionally, only when the page has finished loading (on the window load event) to prevent blocking (the script is ~260KB). When instantiating the plugin, a Promise object is returned under the promise instance property, so you can do something like iti.promise.then(callback) to know when initialisation requests like this have finished. See Utilities Script for more information.

If you want more control over when this file is lazy-loaded, you can manually invoke the attachUtils static method whenever you like, instead of using the loadUtils initialisation option.