Initialisation Options

When you initialise the plugin, the first argument is the input element, and the second is an object containing any initialisation options you want, which are detailed below. Note: any options that take country codes should be ISO 3166-1 alpha-2 codes.

allowDropdown

Type: Boolean Default: true
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. Play with this option in the Playground.

allowedNumberTypes

Type: String[] Default: ["MOBILE", "FIXED_LINE"]
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. Note: previously named validationNumberTypes.

allowNumberExtensions

Type: Boolean Default: false
Whether or not the validation methods return true for numbers containing extensions, e.g. “+1 702 123-1234 ext. 1234”.

allowPhonewords

Type: Boolean Default: false
Whether or not the validation methods return true for numbers containing phonewords, e.g. “+1 702 FLOWERS”.

autoPlaceholder

Type: String Default: "polite"
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.

containerClass

Type: String Default: ""
Additional classes to add to the (injected) wrapper <div>.

countryNameLocale

Type: String Default: "en"
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".

countryOrder

Type: String[] Default: null
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. Note: this replaces the legacy preferredCountries option (now removed).

countrySearch

Type: Boolean Default: true
Add a search input to the top of the dropdown, so users can filter the displayed countries.

customPlaceholder

Type: Function Default: null
Change the placeholder generated by autoPlaceholder. Must return a string.

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

dropdownContainer

Type: Node Default: null
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.

excludeCountries

Type: String[] Default: []
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.

fixDropdownWidth

Type: Boolean Default: true
Fix the dropdown width to the input width (rather than being as wide as the longest country name). Play with this option in the Playground.

formatAsYouType

Type: Boolean Default: true
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. Note: previously named autoFormat.

formatOnDisplay

Type: Boolean Default: true
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.

geoIpLookup

Type: Function Default: null
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!

hiddenInput

Type: Function Default: null
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">

i18n

Type: Object Default: {}
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. 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`;
    }
  }
});

initialCountry

Type: String Default: ""
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.

loadUtils

Type: () => Promise<module> Default: null
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. 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.

nationalMode

Type: Boolean Default: true
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.

onlyCountries

Type: String[] Default: []
In the dropdown, display only the countries you specify here, using their iso2 codes e.g. ["fr", "de", "es"] - see example. Also see: excludeCountries option.

placeholderNumberType

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

separateDialCode

Type: Boolean Default: false
Display the selected country’s international dial code next to the input, so it looks like it’s part of the typed number. Since the user cannot edit the displayed dial code, they may try to type a new one - in this case, to avoid having two dial codes next to each other, 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). Play with this option in the Playground. Note: previously named showSelectedDialCode.

showFlags

Type: Boolean Default: true
Set this to false to hide the flags, e.g. for political reasons. Instead, it will show a generic globe icon. Play with this option in the Playground.

strictMode

Type: Boolean Default: false
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.

useFullscreenPopup

Type: Boolean Default: true on mobile devices, false otherwise
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.