The options below are shared across the JavaScript plugin and the React, Vue, Angular and Svelte components. Code examples below show the value you pass for each option — with the JS plugin, pass them as properties of the options object, e.g. intlTelInput(input, { initialCountry: "us" }); with the framework components, pass them as individual props (with the same name).
Throughout these docs, “iso2 code” means the two-letter country identifier (ISO 3166-1 alpha-2, e.g. "gb"), and “dial code” means the international calling prefix (e.g. +44).
An array of iso2 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).
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 iso2 code.
Note that on plugin initialisation, a Promise is exposed via the promise property on the plugin instance (accessible directly with the JS plugin, or via a ref in the framework components), so you can await it to know when initialisation requests like this have completed.
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!
Note
*The ipapi service used in the example above (and across this site) has a limited free tier that stops working once its quota is reached. For production, you should either sign up for a paid plan, swap in another IP-lookup provider, or roll your own solution — the plugin just cares that you eventually call success(iso2Code) or failure().
Set the initial country selection by specifying its iso2 code, e.g. "us" for the United States. 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 initialCountry set to "de" (Germany) in the Playground.
Warning
Only set this if you’re sure of the user’s country. If set incorrectly and the user auto-fills their national number and submits without checking, the number can pass validation but be stored with the wrong dial code.
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.
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
The positioning is broken by scrolling, so the dropdown will automatically close on the window scroll event. This also applies to the fullscreen popup.
Display the selected country’s international dial code next to the input, so it looks like it’s part of the typed number, but is actually separate (they cannot delete it). This makes it clear to the user which dial code is currently selected and that they are entering their number in international format. Note: previously named showSelectedDialCode.
If the user tries to type a new dial code (as well as the displayed one), we automatically open the country dropdown and focus the search input, so the dial code appears there instead - this way, 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).
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 narrow viewports (or on touch devices with limited vertical space), to make better use of the available space (similar to how a native <select> works), and as an inline dropdown on larger screens.
Try the plugin with this option enabled on 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.
Customise the placeholder text. Your function receives the example number (used as the default placeholder), along with the selected country data, and whatever string you return is used as the placeholder instead.
For example, the snippet below masks each digit with an X, or falls back to "Enter number" when no country is selected:
When no country is selected (globe state), exampleNumber is an empty string and selectedCountryData is null, so remember to guard against null when reading properties off it.
View the plugin with this enabled in the Playground.
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.
View the plugin with this set to "FIXED_LINE" 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. Note: previously named autoFormat.
Try the plugin with this disabled 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.
As the user types (or pastes) in the input, reject 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.
strictMode silently drops rejected input by default — the simplest way to surface that to the user is to enable strictRejectAnimation for a built-in shake/flash animation. For richer feedback (e.g. a toast explaining why input was rejected), listen for the strict:reject event (or use the equivalent onStrictReject / strictReject callback in the component wrappers). For a live example, try typing an alphabetic character in the telephone input on the homepage, which uses a Bootstrap toast.
When strictMode is enabled, play a subtle animation any time a whole keystroke or paste is rejected — a brief shake by default, or a background-colour flash for users with prefers-reduced-motion. Partial paste sanitisation (e.g. only some characters stripped) does not trigger it. The flash colour can be customised via the --iti-strict-reject-flash-color CSS variable.
Specify an array of keys from the enum intlTelInput.utils.numberType to set the number type(s) to enforce during validation, as well as the maximum number length to enforce with strictMode. Set it to null to not enforce any particular type (not recommended*).
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.
*It’s best to be as specific as possible, rather than using the catch-all value of null. isValidNumber works by checking the number’s length, and some number types allow very short lengths. For example, Norwegian mobile and landline numbers are 8 digits long, so by default that’s the only valid length. But Norwegian UAN numbers can be only 5 digits long, so if you set allowedNumberTypes to null, validation will pass for any number that is 5-8 digits long.
Whether or not the validation methods return true for numbers containing phonewords, e.g. “+1 702 FLOWERS”.
Note
When processing phoneword numbers, the plugin will automatically convert them to digits e.g. via getNumber, or when initialising the plugin on an input containing a phoneword number.
The locale to pass to Intl.DisplayNames to generate the country names. Should adhere to the BCP 47 standard, e.g. "zh" (Chinese), or "zh-Hans" (Simplified Chinese). For translating the other UI strings, like the country search placeholder, see i18n below.
Translate the plugin’s UI strings (country search placeholder, no-results message, ARIA labels). For translating country names, see countryNameLocale above.
We ship translations for 45 locales — import one and pass it in as the i18n option:
import { fr } from "intl-tel-input/i18n";
See the Localisation docs for overriding individual keys, defining custom translations, and the full list of translatable keys. Note: previously named localizedCountries.
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’s iso2 code. This is useful for old-fashioned, page-load form submissions to ensure the full international number and iso2 code are captured, especially when nationalMode or separateDialCode is enabled. See example.
This option 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 iso2 code, respectively.
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.
This is one way to lazy load the included utils.js (to enable formatting/validation, etc) - see Loading The Utils 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) if you use a bundler like Webpack, Vite or Parcel, you can import it directly from the package, or (B) from a URL, either a CDN or your own hosted version of utils.js. Note: this replaces the utilsScript option (now removed).
(A) with a bundler, import the utils module directly from the package
// modern bundlers will split this out into a separate chunk and fetch it only when needed
() => import("intl-tel-input/utils")
(B) import utils module from a URL (CDN or your own hosted version)
The module is only loaded once the plugin initialises, and additionally, only once the page has finished loading (on the window load event) to prevent blocking (the script is ~260KB). The promise property on the plugin instance resolves once loading is complete — see Utils Script for more information.
