React component

A React component for the intl-tel-input JavaScript plugin. View the source code, see a live demo on the React component example page, or follow the README to run the full set of demos locally.

Contents

Installation

First, install the package:

npm install intl-tel-input

Then, add something like this to your code:

import IntlTelInput from "intl-tel-input/react";
import "intl-tel-input/styles";

const PhoneInput = () => (
  <IntlTelInput
    initialCountry="us"
    loadUtils={() => import("intl-tel-input/utils")}
  />
);

Note

The utils script (~260KB) is loaded separately. The example above passes a dynamic import to loadUtils — modern bundlers split this into its own lazy-loaded chunk, so it doesn’t hit your initial bundle. Alternatively, if IntlTelInput is already lazy-loaded in your app, import from "intl-tel-input/reactWithUtils" to bundle utils directly.

See Best practices for general advice on validation, E.164 storage, initial country, and localisation.

Props

Any of the plugin’s initialisation options (like initialCountry) can also be passed as a prop.

disabled

Type: boolean
Default: false

Disables both the telephone input and the selected country button. Use this instead of inputProps.disabled, as this disables the country button too.

inputProps

Type: object
Default: {}

The props to pass to the input element, e.g. id, className, placeholder, required, onBlur, defaultValue etc. Use defaultValue to set the initial value of the input - this will get auto-formatted on init (according to formatOnDisplay initialisation option).

Note

The following keys are reserved for the component/plugin integration and will be ignored: type, ref, onInput, value, disabled, readOnly. Use the component props (disabled, readOnly) and the callback props instead.

onChangeCountry

Type: (iso2: string) => void
Default: null

A handler to be called when the selected country changes. Receives the new country’s iso2 code (e.g. "gb"), or "" if no country is selected.

onChangeErrorCode

Type: (errorCode: number | null) => void
Default: null

A handler to be called when the number validation error changes. Receives an integer that matches the intlTelInput.utils.validationError enum, or null if the number is valid. See Deriving a user-facing error message for how to turn the error code into a message. Requires the utils script to be loaded (see above).

onChangeNumber

Type: (number: string) => void
Default: null

A handler to be called when the number changes. Receives the new number in standardised E.164 format (e.g. "+447700900123"), or "" if the input is empty. Requires the utils script to be loaded (see above).

onChangeValidity

Type: (isValid: boolean) => void
Default: null

A handler to be called when the number validity changes. Receives the new validity boolean. Requires the utils script to be loaded (see above).

onCloseCountryDropdown

Type: () => void
Default: null

A handler to be called when the country dropdown closes.

onOpenCountryDropdown

Type: () => void
Default: null

A handler to be called when the country dropdown opens.

onStrictReject

Type: (source: "key" | "paste", rejectedInput: string, reason: "invalid" | "max-length") => void
Default: null

A handler to be called when strictMode rejects or modifies input. For most cases, strictRejectAnimation gives you a built-in shake/flash animation without writing any handler code — only reach for onStrictReject when you need custom feedback (e.g. a toast that explains why the input was rejected).

The handler receives three arguments describing what was rejected and why:

  • source: either "key" (a keystroke) or "paste" (a clipboard paste).
  • rejectedInput: the raw string that was rejected or stripped — for "key" this is the single character pressed, and for "paste" it’s the full pasted text.
  • reason: either "invalid" (the input contained a disallowed character) or "max-length" (accepting the input would have exceeded the maximum valid length for the selected country).

Here is an example that selects a user-facing message based on these args:

if (reason === "max-length") msg = "Maximum length reached for this country";
else if (source === "paste") msg = "Stripped invalid characters from pasted text";
else msg = `Character not allowed: "${rejectedInput}"`;
readOnly

Type: boolean
Default: false

Makes the telephone input read-only and disables the selected country button. Use this instead of inputProps.readOnly, as this disables the country button too.

usePreciseValidation

Type: boolean Default: false

By default, we use isValidNumber for validation, but if you’d rather use isValidNumberPrecise, you can set this to true.

value

Type: string
Default: undefined

Optional controlled value. If provided, the component becomes controlled — whenever this prop changes, the input is updated via setNumber (skipped while the input is focused, to avoid disrupting typing). Leave it undefined to keep the component uncontrolled and use inputProps.defaultValue for the initial value instead.

Important

When using value, you should also use onChangeNumber to keep the value in sync with user input, otherwise programmatic updates (e.g. clearing the input) may not work as expected.

Plugin initialisation options

All of the plugin’s initialisation options are supported as individual React props using the same option name. For example:

<IntlTelInput initialCountry="us" />

Note

If you’re migrating from an older version, the previous initOptions={{ initialCountry: "us" }} style is no longer supported — pass each option as its own prop instead.

Accessing instance methods

You can access all of the plugin’s instance methods (setNumber, setCountry, setPlaceholderNumberType, etc) by passing a ref into the IntlTelInput component (using the ref prop), and then calling ref.current.getInstance(), e.g. ref.current.getInstance().setNumber(...);. See the Set Number demo for a full example. You can also access the input DOM element in a similar way: ref.current.getInput().

Accessing static methods

You can access all of the plugin’s static methods by importing intlTelInput from the same file as the React component, e.g. import { intlTelInput } from "intl-tel-input/react" (note the lower case “i” in “intlTelInput”). You can then use this as you would with the main plugin, e.g. intlTelInput.getCountryData() or intlTelInput.utils.numberType etc.

Edit this page