FAQ

Do I need the utils script?

It depends on which features you want.

The utils script enables things like:

  • Formatting and validation helpers
  • Automatic country-specific placeholders

See Utils script for how to load it and what it’s used for.

What format should I store phone numbers in?

In most cases you should store phone numbers in standardised international format (E.164), e.g. +447740123456. That way, you can just store a single string that contains all the information you need (the phone number and the country it belongs to).

You can always get the E.164 number using getNumber, even if the user has entered their number in national format, or separateDialCode is enabled. For displaying numbers back to the user (e.g. on a user profile page), simply initialise it on an input containing an E.164 number, and it will automatically select the right flag and format the number according to your settings (national format by default).

How do I submit the full international number in a normal HTML form?

Use the hiddenInputs option.

That option listens for the form submit event and injects hidden input(s) containing the full international number (and optionally the selected country’s iso2 code), so they’re included in the form post.

See the Hidden input example.

How do I set the initial country?

Use the initialCountry option.

  • If you already know the user’s country, set it to the relevant iso2 code, e.g. "us".
  • If you don’t, provide initialCountryLookup to detect the user’s country (e.g. via an IP lookup service).

Can I translate the UI and country names?

Yes.

  • Country names can be localised using countryNameLocale (uses Intl.DisplayNames).
  • UI strings (including accessibility strings) can be translated using uiTranslations.

See Localisation for more information.

How do I validate a number?

If you’re using the utils script, you can validate numbers and show useful error messages.

How do I restore the preferredCountries divider?

The legacy preferredCountries option has been replaced by countryOrder, which takes the same array of iso2 codes. So before you had:

preferredCountries: ["us", "gb"]

And now you have:

countryOrder: ["us", "gb"]

The one visual difference is that the old option rendered a grey divider below the preferred group, and countryOrder does not. If you want that divider back, you can add the following CSS rule.

If you have countrySearch enabled (the default), use this version, which hides the divider while searching:

/* Replace "us" with the iso2 code of the last country in your preferred group */
.iti__country-selector:has(.iti__search-input:placeholder-shown) .iti__country[data-iso2="us"] {
  border-bottom: 1px solid var(--iti-border-color);
}

If you have countrySearch disabled, this simpler version is enough:

/* Replace "us" with the iso2 code of the last country in your preferred group */
.iti__country[data-iso2="us"] {
  border-bottom: 1px solid var(--iti-border-color);
}

Something looks broken — where should I look first?

A lot of “broken” behaviour is caused by layout/CSS or initialising on an input that isn’t in the DOM yet. Check devtools: is the CSS loading? Have you overridden the flag paths correctly, and are the flag images loading?

Also see Troubleshooting.

Still stuck?

Try searching the GitHub issues — chances are someone has had the same question before.

Edit this page