PhoneInput
International phone number input with country selector
Source
Package
Usage
PhoneInput is an international phone number input with a country selector
and per-country formatting. Set defaultCountry prop: without it, no country is selected
until the user picks one or types a dial code:
PhoneInput with uncontrolled forms
Set name to submit the formatted phone number shown in the input. The raw number is available from onChange:
Input features
PhoneInput component supports Input and Input.Wrapper component features and all input element props. The PhoneInput documentation does not include all features supported by the component – see the Input documentation to learn about all available features.
Input description
Loading state
Set loading prop to display a loading indicator in the input:
Controlled
onChange is called with the raw value and a details object with the formatted value and
the selected country:
Raw value: +1 Formatted: Country: –
Phone extensions
Set withExtension to allow extensions separated by x, for example +12025551234x1234.
The extension is included in value and available separately as details.extension in onChange.
With this prop, details.extension is an empty string when no extension digits are entered:
Enter an extension after x
+12025551234x1234
Preferred countries
Use preferredCountries prop to pin countries to the top of the dropdown:
Filter countries
Use onlyCountries to show only specific countries or excludeCountries to hide some of them:
Virtualized dropdown
Use virtualizer to render countries as they scroll into view. Open the country picker to choose a dialing code:
Custom flags
Use renderFlag to display SVG flags from country-flag-icons:
Searchable
Country search is enabled by default. Set searchable={false} to disable it:
Country auto-detection
Set withCountryAutoDetect to switch the country as the user types a dial code.
It also detects area codes, such as +1 204 for Canada:
Shared dial codes
Countries sharing a dial code are selected by area code and priority by default.
Use resolveCountry to choose one by ISO2 code, or return undefined to keep the default:
National prefixes
PhoneInput removes known trunk prefixes from pasted national numbers. For example, pasting
8 999 123-45-67 with Russia selected produces +79991234567. Clearing the input emits ''.
In an empty international input, a typed leading trunk prefix is also removed.
Typing an explicit dial code, such as +7, preserves the national digits that follow in both "auto" and "strip" modes.
Ambiguous digits typed after a prefilled dial code are preserved by default. Set nationalPrefixBehavior="strip"
when users should enter numbers in national form, or "preserve" to disable prefix removal.
With "strip", unprefixed numbers use the selected country. Include + to enter another country's dial code:
Localization
Use renderCountryOption to change how countries are displayed in the dropdown,
for example to translate country names:
getCountryLabel returns the translated name of a country. It is used as the
country button label for screen readers and in the dropdown search, so users
can search by translated names. searchPlaceholder and selectCountryLabel
translate the search input placeholder and the button label shown before a
country is selected:
Dropdown position
Disabled state
Read only
Error state
Invalid phone number
Success state
Looks good!
Styles API
PhoneInput supports the Styles API; you can add styles to any inner element of the component with the classNames prop. Follow the Styles API documentation to learn more.
Component Styles API
Hover or focus a selector to highlight its elements
Get element ref
Accessibility
If PhoneInput is used without the label prop, it will not be announced properly by screen readers:
Set aria-label to make the input accessible. In this case the label will not be visible, but screen readers will announce it:
If the label prop is set, the input will be accessible and it is not required to set aria-label: