Best practices

General advice for getting the most out of intl-tel-input, whether you’re using the vanilla JavaScript library or one of the framework components (React, Vue, Angular, Svelte).

Load the utils module

Load utils.js to enable formatting, validation, and generating placeholder numbers.

Store and restore numbers in E.164 format

Since the dial code is embedded in the number (e.g. "+17024181234"), you don’t need to store the country separately. To read the number out in E.164, use getNumber (or your component’s change callback / bound value). To restore it, pass the stored E.164 number as the input’s starting value on initialisation — the core library will automatically set the country^* and format the number according to your options.

^*Except for some small satellite territories, which share number ranges with the main country, in which case we default to selecting the main country.

Validate before saving

Check the number is valid before storing it, and reject invalid input. Get the validity from isValidNumber (vanilla JS library) or the onChangeValidity / validityChange callback (framework components). Requires the utils module.

Show a user-facing error message

When a number is invalid, you’ll get an error code (from getValidationError for the vanilla JS library, or via the onChangeErrorCode / errorCodeChange callback for the framework components). Mapping the error codes to user-facing messages is left to you because the wording belongs to your app. Here is a reasonable starting point — a getErrorMessage helper:

const getErrorMessage = (number, errorCode) => {
  if (!number) return "Please enter a number";
  const { VALIDATION_ERROR } = intlTelInput;
  switch (errorCode) {
    case VALIDATION_ERROR.INVALID_COUNTRY_CODE: return "Invalid dial code";
    case VALIDATION_ERROR.TOO_SHORT: return "Too short";
    case VALIDATION_ERROR.TOO_LONG: return "Too long";
    default: return "Invalid number";
  }
};

Keep strict mode on, with rejection feedback

strictMode is on by default and rejects non-numeric characters while capping the length at the country’s max as the user types. Just as importantly, the rejection shouldn’t be silent — by default, strictRejectAnimation plays a built-in shake/flash animation so the user notices. For richer feedback (e.g. a toast that explains why the input was rejected), listen for the strict:reject event (vanilla JS library) or use the equivalent onStrictReject / strictReject callback (framework components).

Set the initial country

If you know the user’s country, set initialCountry (e.g. "us"). If you don’t, set the initialCountryLookup option to determine the country from their IP address — see example.

Translate the UI

If you know the user’s language, you can translate the country names and UI strings — see Localisation.