Home>Programming related>Other source code

i18n
Type: Object Default: {}
Allow localisation/customisation of the 200+ country names, as well as other user interface text (e.g. the placeholder text for the country search input). The easiest way to do this is to simply import one of the provided translation modules and set i18n to that value (see option 1 below). You can also override one or more individual keys this way (see option 1 below). Alternatively, you can provide your own custom translations (see option 2 below). If providing your own, you will need to specify all the country names (which can be copied from the country-list project e.g. here are the country names in French), as well as a few 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, as we automatically pull in the country names from the country-list project.

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",
  },
});

Option 2: define your own custom translations

intlTelInput(input, {
  i18n: {
    // Country names - see the full list in src/js/intl-tel-input/i18n/en/countries.ts
    af: "Afghanistan",
    al: "Albania",
    dz: "Algeria",
    as: "American Samoa",
    ad: "Andorra",
    ...
    // Aria label for the selected country element
    selectedCountryAriaLabel: "Selected country",
    // Screen reader text for when no country is selected
    noCountrySelected: "No country selected",
    // Aria label for the country list element
    countryListAriaLabel: "List of countries",
    // Placeholder for the search input in the dropdown
    searchPlaceholder: "Search",
    // Screen reader text for when the search produces no results
    zeroSearchResults: "No results found",
    // Screen reader text for when the search produces 1 result
    oneSearchResult: "1 result found",
    // Screen reader text for when the search produces multiple results
    multipleSearchResults: "${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 that however you use initialCountry, it will not update the country selection if the input already contains a number with an international dial code.

loadUtilsOnInit (see v25 discussion)
Type: String or () => Promise Default: "" Example: "/build/js/utils.js"

This is one way to (lazy) load the included utils.js (to enable formatting/validation etc) - see Loading The Utilities Script for more options. You will need to host the utils.js file, and then set the loadUtilsOnInit option to that URL, or alternatively just point it to a CDN hosted version e.g. "https://cdn.jsdelivr.net/npm/[email protected]/build/js/utils.js". The script is loaded via a dynamic import statement, which means the URL cannot be relative - it must be absolute.

Alternatively, this can be a function that returns a promise for the utils module. When using a bundler like Webpack, this can be used to tell the bundler that the utils script should be kept in a separate file from the rest of your code. For example: { loadUtilsOnInit: () => import("intl-tel-input/utils") }.

The script is only fetched 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.

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 - see example. 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.

onlyCountries
Type: Array Default: []
In the dropdown, display only the countries you specify - see example.

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 on Storybook (using the React component).

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 on Storybook (using the React component).

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 new 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 on Storybook (using the React component).

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 validationNumberType). Requires the utils script to be loaded. See example.

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 it will break the layout. Instead, you must insert it before the container (with class iti).

Dropdown position
The dropdown should automatically appear above/below the input depending on the available space. For this to work properly, you must only initialise the plugin after the has been added to the DOM.

Placeholders
To get the automatic country-specific placeholders, simply omit the placeholder attribute on the , or set autoPlaceholder to "aggressive" to override any existing placeholder,

Bootstrap input groups
A couple of CSS fixes are required to get the plugin to play nice with Bootstrap input groups. You can see a Codepen here.
Note: there is currently a bug in Mobile Safari which causes a crash when you click the dropdown arrow (a CSS triangle) inside an input group. The simplest workaround is to remove the CSS triangle with this line:

.iti__arrow { border: none; }

Contributing

See the contributing guide for instructions on setting up the project and making changes, and also on how to update to a new version of libphonenumber, how to update the flag images, or how to add a new translation.

Attributions

  • Flag images from flag-icons
  • Original country data from mledoze's World countries in JSON, CSV and XML
  • Formatting/validation/example number code from libphonenumber
  • Feature contributions are listed in the wiki: Contributions

User testing powered by BrowserStack Open-Source Program

Browser testing via

Expand
Additional Information
  • Version v24.7.0
  • Type Other source code
  • Update Time 2024-11-12
  • size
  • Language Simplified Chinese