Generating placeholder numbers for every country - even specify the type of number (e.g. mobile) using the placeholderNumberType option
Extracting the standardised (E.164) international number with getNumber even when using numberDisplayFormat"NATIONAL"
International number formatting/validation is hard (it varies by country/district, and we currently support ~230 countries). The only comprehensive solution we have found is libphonenumber, from which we have precompiled the relevant parts into a single JavaScript file, included in the build directory. Unfortunately, even after modification, it is still ~260KB. See the section below on the best way to load it.
The utils script adds ~260KB on top of the ~30KB core library. There are two ways to load it — if you’re not sure which to pick, use Option 1. It keeps your initial page load small, which is the safer default for most sites.
Option 1: Lazy load utils on demand (recommended)
Use the loadUtils option to fetch the utils separately. The core library/component loads quickly (~30KB); the ~260KB utils file is fetched in the background after initialisation, so formatting/validation kicks in shortly after the input appears without blocking your initial page load.
Option 2: Use the all-in-one bundle
Each distribution ships a companion entry point that bundles utils directly — intl-tel-input/intlTelInputWithUtils for the vanilla JavaScript library, @intl-tel-input/react/with-utils for React, @intl-tel-input/vue/with-utils for Vue, and so on. Everything works out of the box, with no extra configuration. Best if you’re already lazy loading the core library, or if the extra ~260KB up front isn’t a concern.
Once the utils script has loaded, its functions are exposed on intlTelInput.utils, and can be called directly (without a library instance). Most of the instance methods that require utils are thin wrappers around these — use the instance methods when you have an iti to hand, and reach for these directly when you don’t (e.g. validating a stored number on its own).
All functions take a lowercase ISO2 country code (e.g. "us"), and silently fall back to a safe default (the original input, an empty string, null, or false) if parsing fails — they don’t throw.
Important
These functions are only available after the utils script has loaded. See Loading the utils script, and either await iti.promise (on an instance) or await intlTelInput.attachUtils(...) (without one) before calling them.
Get the national significant number (NSN) — the number with any international dial code and national prefix stripped off. Returns an empty string if it can’t be parsed.
In some countries (e.g. the US) there’s no way to differentiate between fixed-line and mobile numbers, so in those cases it will return "FIXED_LINE_OR_MOBILE".
Get more information about an invalid number — returns a ValidationError string (e.g. "TOO_SHORT", "TOO_LONG", "INVALID_COUNTRY_CODE"), or null if it can’t be determined. See Show a user-facing error message for a worked example.
Check if the given number is valid based on its length. Used by iti.isValidNumber(). Optionally pass an array of NumberType values to restrict the check to specific types. More future-proof than utils.isValidNumberPrecise, as country length rules rarely change. Note: previously named utils.isPossibleNumber.
When you pass ["MOBILE"] or ["FIXED_LINE"] for the numberTypes param, "FIXED_LINE_OR_MOBILE" is automatically included — so countries like the US (where the two can’t be told apart) still match correctly.
Check if the given number is valid using precise country/area-code matching rules. Used by iti.isValidNumberPrecise(). Optionally pass an array of NumberType values to restrict the check to specific types. Note that these rules change each month for various countries, so the package needs to be kept up-to-date (e.g. via an automated script) — otherwise you may start rejecting valid numbers. For a simpler and more future-proof check, see utils.isValidNumber. Note: previously named utils.isValidNumber.
When you pass ["MOBILE"] or ["FIXED_LINE"] for the numberTypes param, "FIXED_LINE_OR_MOBILE" is automatically included — so countries like the US (where the two can’t be told apart) still match correctly.