React component

A React component for the intl-tel-input JavaScript plugin. View the source code.

Demo

You can see a live demo and example code on the React component example page.

Alternatively, download and build the project yourself in 3 simple steps. You just need to initialise the submodules with git submodule update --init --recursive, then run npm install, and then npm run build. You should now be able to open the validation demo page /react/demo/validation/validation.html in your browser and give it a try. View other available demos.

Getting started

First, install the package:

npm install intl-tel-input

Then, add something like this to your code:

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

<IntlTelInput
  onChangeNumber={setNumber}
  onChangeValidity={setIsValid}
  initialCountry="us"
/>

See the Validation demo for a more fleshed-out example of how to handle validation.

A note on the utils script (~260KB): if you’re lazy loading the IntlTelInput chunk (and so less worried about filesize), then you can just import IntlTelInput from "intl-tel-input/reactWithUtils", to include the utils script. Alternatively, if you use the main "intl-tel-input/react" import, then you should couple this with the loadUtils initialisation option - you will need to host the utils.js file, and then set the loadUtils option to that URL, or just point it to a CDN-hosted version, e.g. "https://cdn.jsdelivr.net/npm/[email protected]/dist/js/utils.js".

Props

Here’s a list of all of the current props you can pass to the IntlTelInput React component.

disabled

Type: Boolean
Default: false

Disables both the telephone input and the selected country button. Note: We recommend using this instead of inputProps.disabled.

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: Function
Default: null

A handler to be called when the selected country changes. It will receive the new country iso2 code, e.g. “gb” for the UK.

onChangeErrorCode

Type: Function
Default: null

A handler to be called when the number validation error changes. It will receive the new error code (or null). Requires the utils script to be loaded (see above).

onChangeNumber

Type: Function
Default: null

A handler to be called when the number changes. For valid numbers (see onChangeValidity), it will receive the new number in the standard E.164 format. Requires the utils script to be loaded (see above).

onChangeValidity

Type: Function
Default: null

A handler to be called when the number validity changes, e.g. to true/false. It will receive the new isValid boolean. Requires the utils script to be loaded (see above).

readOnly

Type: Boolean
Default: false

Makes the telephone input read-only and disables the selected country button. Note: We recommend using this instead of inputProps.readOnly.

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.

Initialisation options

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

For example, if you’re migrating from older usage like:

<IntlTelInput initOptions={{ initialCountry: "us" }} />

Use:

<IntlTelInput initialCountry="us" />

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.

Troubleshooting

Error when toggling presence of IntlTelInput component

Error message: Failed to execute 'removeChild' on 'Node': The node to be removed is not a child of this node.

Solution: wrap the component in a div, e.g.

{showIntlTelInput && (
    <div>
        <IntlTelInput />
    </div>
)}

Edit this page