react-phone-number-input
v3.4.14TypeScript
Telephone number input React component
1.4M/weekUpdated 2 months agoMITUnpacked: 10.1 MB
Published by catamphetamine
react-phone-number-input
International phone number
See Demo
Install
``
npm install react-phone-number-input --save
`
Alternatively, one could include it on a web page directly via a tag.
This component installs libphonenumber-js dependency for phone number parsing and formatting.
Use
This component comes in two variants: "with country select" and "without country select".
With country select
"With country select" component requires two properties: value and onChange(value). See the list of all available props.
`js
import 'react-phone-number-input/style.css'
import PhoneInput from 'react-phone-number-input'
function Example() {
// value will be the parsed phone number in E.164 format.
// Example: "+12133734253".
const [value, setValue] = useState()
return (
value={value}
onChange={setValue}/>
)
}
`
The value argument of onChange(value) function will be the parsed phone number in E.164 format. For example, if a user chooses "United States" and enters (213) 373-4253 in the input field then onChange(value) will be called with value being "+12133734253".
Any "falsy" value like undefined, null or an empty string "" is treated like "empty". In case of the onChange() function's value argument though it's always undefined for an "empty" value, i.e. when the user clears the input value, onChange() is called with undefined as an argument. Perhaps null would've been better, but historically it has been undefined.
All unknown properties will be passed through to the phone number component.
To set a default country, pass a defaultCountry property (must be a supported country code). Example: .
To get the currently selected country, pass an onCountryChange(country) property.
To get the country of a complete phone number, use parsePhoneNumber(value): parsePhoneNumber(value) && parsePhoneNumber(value).country.
To format value back to a human-readable phone number, use formatPhoneNumber(value) or formatPhoneNumberIntl(value).
#### CSS
"With country select" component comes with a style.css stylesheet. All CSS class names start with .PhoneInput. Additional "modifier" CSS classes: .PhoneInput--focus for :focus, .PhoneInput--disabled for :disabled, .PhoneInput--readOnly for [readonly].
The stylesheet uses native CSS variables for convenience. Native CSS variables work in all modern browsers, but older ones like Internet Explorer wont't support them. For compatibility with such older browsers one can use a CSS transformer like PostCSS with a "CSS custom properties" plugin like postcss-custom-properties.
Some of the CSS variables:
* --PhoneInputCountryFlag-height — Flag icon height.
* --PhoneInputCountryFlag-borderColor — Flag icon outline color.
* --PhoneInputCountrySelectArrow-color — Country select arrow color.
* --PhoneInputCountrySelectArrow-opacity — Country select arrow opacity (when not :focused).
* --PhoneInput-color--focus — Flag icon :focus outline color, and also country select arrow :focus color.
* …
##### When using Webpack
When using Webpack, include the stylesheet on a page via import:
`js
import 'react-phone-number-input/style.css'
`
For supporting old browsers like Internet Explorer, one could
use postcss-loader with a CSS autoprefixer and postcss-custom-properties transpiler.
##### When not using Webpack
Get style.css file from this package, optionally process it with a CSS autoprefixer and postcss-custom-properties transpiler for supporting old web browsers, and then include the CSS file on a page.
`html
`
Or include the style.css file directly from a CDN if you don't have to support Internet Explorer.
Without country select
"Without country select" component is just a minimal "barebones" phone number , without any CSS.
`js
import PhoneInput from 'react-phone-number-input/input'
function Example() {
// value holds the parsed phone number (in E.164 format).
// When the input is empty, or when there's not enough digits, value is undefined.
//
// Example: "+12133734253".
//
const [value, setValue] = useState()
// Specifying a country only allows input of phone numbers belonging to that specific country.
// Not specifying a country only allows input of any phone number in international format
// (i.e. starting with a "+").
//
return (
value={value}
onChange={setValue}
/>
)
}
`
Available properties:
* country: string? — If country is specified then it only allows input of phone numbers that belong to that specific country. When specified, the value must be a supported country code. Example: country="US".
* defaultCountry: string? — If defaultCountry is specified then phone numbers can be input either in "international" format for any country or in "national" format for that specific country. Basically, it imposes a country restriction but only on phone numbers in "national" format while allowing any phone numbers in "international" format. In other words: "When the country is not specified in the phone number itself, assume it to be ... by default". When specified, the value must be a supported country code. Example: defaultCountry="US".
* international: boolean? — Controls which phone number format is allowed: "international" or "national" (or both). Set to true to only allow "international" format. Set to false to only allow "national" format.
* When international property is not explicitly specified, its default value will be determined based on the values of other properties such as country or defaultCountry:
* When country is specified, the default value of international property is false, meaning that the phone number can only be input in "national" format for that country.
* When defaultCountry is specified, the phone number could be input either in "international" format or in "national" format for the defaultCountry, so the default value of international property stays undefined.
* When no country or defaultCountry are specified, the phone number can only be input in "international" format (without any country restrictions), so the default value of the international property is true.
* When country is specified and international property is explicitly set to true, the phone number can only be input in "international" format for that country.
* In that case, by default, the "country calling code" part — for example, "+1" when country is "US" — is not included in the input field.
* Example: if country is "US" and international property is true then the phone number can only be input in "international" format for US, without the leading "+1" part, so it would look like "213 373 4253" rather than "+1 213 373 4253".
* This is done intentionally so that a developer could build their own multi-country phone number input component where the "country calling code" part like "+1" is selectable separately before the main input field.
* To disable this behavior, set withCountryCallingCode property to true, and the "country calling code" part like "+1" will be part of the input field, but be aware that it still won't be editable because otherwise it would contradict the country property.
* Example: if country is "US" and international property is true and withCountryCallingCode property is true then the phone number can only be input in "international" format for US, with the fixed leading "+1" part, so it would look like "+1 213 373 4253".
* withCountryCallingCode: boolean? — If country is specified and international property is true then the phone number can only be input in "international" format for that country. By default, the "country calling code" part — for example, +1 when country is US — is not included in the input field. To change that, set withCountryCallingCode property to true, and it will include the "country calling code" part in the input field, although it will still be non-editable. See the demo for an example.
* useNationalFormatForDefaultCountryValue: boolean? — By default, when defaultCountry is defined and the initial phone number belongs to the defaultCountry, that initial phone number is formatted in "national" format. A developer might rather prefer it to use "international" format for that, in which case set useNationalFormatForDefaultCountryValue property value to false.
* value: string? — Phone number value. Examples: undefined, "+12133734253".
* onChange(value: string?) — Updates the value (to undefined in case it's empty).
* inputComponent: component? — Custom input component.
* By default, it's a generic DOM component.
* Any custom input component implementation must use React.forwardRef() to "forward" ref to the underlying "core" component.
* Receives properties:
* value: string
* onChange(event: Event)
* Any other properties that were passed to and aren't specifically handled by this library. For example, type="tel", autoComplete="tel", etc.
* smartCaret: boolean? — When the user attempts to insert a digit somewhere in the middle of a phone number, the caret position is moved right before the next available digit skipping any punctuation in between. This is called "smart" caret positioning. Another case would be the phone number format changing as a result of the user inserting the digit somewhere in the middle, which would require re-positioning the caret because all digit positions have changed. This "smart" caret positioning feature can be turned off by passing smartCaret={false} property: use it in case of any possible issues with caret position during phone number input.
See the demo for the examples.
For those who want to pass custom metadata there's react-phone-number-input/input-core sub-package.
This library also exports getCountries() and getCountryCallingCode(country) functions that a developer could use to construct their own custom country select. Such custom country could be used in conjunction with the "without country select" described above.
Creating a custom country <select/>
####
`js
import PropTypes from 'prop-types'
import { getCountries, getCountryCallingCode } from 'react-phone-number-input'
const CountrySelect = ({ value, onChange, labels, ...rest }) => (
{...rest}
value={value}
onChange={event => onChange(event.target.value || undefined)}>
{getCountries().map((country) => (
))}
)
CountrySelect.propTypes = {
value: PropTypes.string,
onChange: PropTypes.func.isRequired,
labels: PropTypes.objectOf(PropTypes.string).isRequired
}
`
Use:
`js
import PhoneInput from 'react-phone-number-input/input'
import en from 'react-phone-number-input/locale/en'
import CountrySelect from './CountrySelect'
function Example() {
const [country, setCountry] = useState('US')
const [value, setValue] = useState()
return (
value={country}
onChange={setCountry}/>
value={value}
onChange={setValue}/>
)
}
`
React Native
This library also includes a React Native version of a "without country select" component. Post bug reports and suggestions in the feedback thread.
`js
import React, { useState } from 'react'
import PhoneInput from 'react-phone-number-input/react-native-input'
function Example() {
const [value, setValue] = useState()
return (
country="US"
value={value}
onChange={setValue}
/>
)
}
`
Accepts the same properties as the web version of "without country select" component, with the following differences:
* smartCaret: boolean? property is not supported because "smart caret" positioning feature is not implemented in the React Native component.
* inputComponent: component? — By default, it renders a generic . A custom input component can be passed. Such custom input component must forwardRef() to the underlying input field. The input component receives properties:
* value: string
* onChangeText(value: string)
* all the "rest" of the properties that're not handled by this library, like keyboardType="phone-pad", autoCompleteType="tel", etc.
Utility
This package exports several utility functions.
$3
Formats value as a "local" phone number.
`js
import { formatPhoneNumber } from 'react-phone-number-input'
formatPhoneNumber('+12133734253') === '(213) 373-4253'
`
$3
Formats value as an "international" phone number.
`js
import { formatPhoneNumberIntl } from 'react-phone-number-input'
formatPhoneNumberIntl('+12133734253') === '+1 213 373 4253'
`
$3
Checks if a phone number value is a "possible" phone number. A phone number is "possible" when it has valid length. The actual phone number digits aren't validated.
`js
import { isPossiblePhoneNumber } from 'react-phone-number-input'
isPossiblePhoneNumber('+12223333333') === true
`
$3
Checks if a phone number value is a "valid" phone number. A phone number is "valid" when it has valid length, and the actual phone number digits match the regular expressions for that country.
`js
import { isValidPhoneNumber } from 'react-phone-number-input'
isValidPhoneNumber('+12223333333') === false
isValidPhoneNumber('+12133734253') === true
`
By default the component uses min "metadata" which results in less strict validation compared to max or mobile.
I personally don't use isValidPhoneNumber() for phone number validation in my projects. The rationale is that telephone numbering plans can and sometimes do change, meaning that isValidPhoneNumber()function may one day become outdated on a website that isn't actively maintained anymore. Imagine a "promo-site" or a "personal website" being deployed once and then running for years without any maintenance, where a client may be unable to submit a simple "Contact Us" form just because this newly allocated pool of mobile phone numbers wasn't present in that old version of libphonenumber-js bundled in it.
Whenever there's a "business requirement" to validate a phone number that's being input by a user, I prefer using isPossiblePhoneNumber() instead of isValidPhoneNumber(), so that it just validates the phone number length, and doesn't validate the actual phone number digits. But it doesn't mean that you shouldn't use isValidPhoneNumber() — maybe in your case it would make sense.
$3
Parses a PhoneNumber object from a string. This is simply an alias for parsePhoneNumber() from libphonenumber-js. Can be used to get country from value.
`js
import { parsePhoneNumber } from 'react-phone-number-input'
const phoneNumber = parsePhoneNumber('+12133734253')
if (phoneNumber) {
phoneNumber.country === 'US'
}
`
$3
Returns the "country calling code" of a country. The country argument must be a supported country code.
This is simply an alias for getCountryCallingCode() from libphonenumber-js.
`js
import { getCountryCallingCode } from 'react-phone-number-input'
getCountryCallingCode('US') === '1'
`
$3
Checks if a given country code is supported by this library.
This is simply an alias for isSupportedCountry() from libphonenumber-js.
`js
import { isSupportedCountry } from 'react-phone-number-input'
isSupportedCountry('US') === true
`
Flags URL
By default, all flags are linked from country-flag-icons's GitHub pages website as s. Any other flag icons could be used instead by passing a custom flagUrl property (which is "https://purecatamphetamine.github.io/country-flag-icons/3x2/{XX}.svg" by default) and specifying their aspect ratio via --PhoneInputCountryFlag-aspectRatio CSS variable (which is 1.5 by default, meaning "3x2" aspect ratio).
For example, using flagpack "4x3" flag icons would be as simple as:
`css
:root {
--PhoneInputCountryFlag-aspectRatio: 1.333;
}
`
`js
`
Including all flags
Linking flag icons as external s is only done to reduce the overall bundle size, because including all country flags in the code as inline s would increase the bundle size by 44 kB (after gzip).
If bundle size is not an issue (for example, for a standalone non-web application, or an "intranet" application), then all country flags can be included directly in the code by passing the flags property:
`js
import PhoneInput from 'react-phone-number-input'
import flags from 'react-phone-number-input/flags'
`
Localization
Language translation can be applied by passing a custom labels property value. This component comes pre-packaged with several importable translations.
`js
import russianLabels from 'react-phone-number-input/locale/ru'
`
If labels for a certain language are missing, one could submit a pull request to add those.
Where could one get the list of country names for a given language.
####
There's a myriad sources on the internet. Modern web browsers even have an official built-in list of country names in all languages.
For example, one could copy country names from github.com/umpirsky/country-list.
`js
import countryNamesInRussian from 'country-list/data/ru/country.json'
// Outputs a JSON with the country names.
JSON.stringify(
Object.keys(countryNamesInRussian).sort()
.reduce((all, country) => ({
...all,
[country]: countries[country]
}), {}),
null,
'\t'
)
`
####
Note that this library uses the term "country code" rather broadly, including both the official and ISO-3166-1 country codes and a few of unofficial "country codes", so a translation should include the labels for both official and unofficial "country codes".
Also, a translation should include the following miscellaneous labels:
* country — is used as an aria-label for the country dropdown. It could also be used as a label for a hypothetical country name autocomplete input field.
* ZZ — is used when no country is selected.
* phone — could hypothetically be used as a label for the phone number input field.
* ext — could hypothetically be used as a label for a phone number extension input field.
####
The final format for a translation file is:
`js
{
"country": "Phone number country",
"phone": "Phone",
"ext": "ext.",
// The rest are country names, including "unofficial" ones
// like AC, TA, XK, and ZZ for "International".
...,
"RO": "Romania",
"RS": "Serbia",
"RU": "Russia",
...,
"ZZ": "International"
}
`
min vs max vs mobile
This component uses libphonenumber-js which provides different "metadata" sets, "metadata" being a list of phone number parsing and formatting rules for all countries. The complete list of those rules is huge, so libphonenumber-js provides a way to optimize bundle size by choosing between max, min, mobile and "custom" metadata:
* max — The complete metadata set, is about 145 kB in size (libphonenumber-js/metadata.max.json). Choose this when you need the most strict version of isValid(), or if you need to detect phone number type ("fixed line", "mobile", etc).
* min — (default) The smallest metadata set, is about 80 kB in size (libphonenumber-js/metadata.min.json). Choose this by default: when you don't need to detect phone number type ("fixed line", "mobile", etc), or when a basic version of isValid() is enough. The min metadata set doesn't contain the regular expressions for phone number digits validation (via .isValid()) and detecting phone number type (via .getType()) for most countries. In this case, .isValid() still performs some basic phone number validation (for example, checks phone number length), but it doesn't validate phone number digits themselves the way max metadata validation does.
* mobile — The complete metadata set for dealing with mobile numbers _only_, is about 95 kilobytes in size (libphonenumber-js/metadata.mobile.json). Choose this when you need max metadata and when you _only_ accept mobile numbers. Other phone number types will still be parseable, but they won't be recognized as being "valid" (isValidPhoneNumber() will return false).
To use a particular metadata set, simply import functions from a relevant sub-package.
For "with country select" component those're:
* react-phone-number-input/max
* react-phone-number-input/min
* react-phone-number-input/mobile
Importing functions directly from react-phone-number-input effectively results in using the min metadata.
For "without country select" component the sub-packages are:
* react-phone-number-input/input-max
* react-phone-number-input/input (for min)
* react-phone-number-input/input-mobile
Sometimes (rarely) not all countries are needed, and in those cases developers may want to generate their own "custom" metadata set. For those cases, there's a /core sub-package that doesn't come pre-packaged with any default metadata set and instead accepts metadata as a component property and as the last argument of each exported function.
For "with country select" component, the /core export is react-phone-number-input/core, and for "without country select" component, the /core export is react-phone-number-input/input-core.
Bug reporting
If you think that the phone number parsing/formatting/validation engine malfunctions for a particular phone number then it could be for several reasons:
* libphonenumber-js, which is what this package uses internally, parses/formats/validates phone numbers incorrectly. To test if that's the case, follow the instructions outlined in the bug reporting section of libphonenumber-js repo readme.
* react-phone-number-input's exported isValidPhoneNumber() function is a "stripped-down" "min" version of the same function exported from libphonenumber-js package, so if you think that the validation is too lax, use the isValidPhoneNumber() function from libphonenumber-js/max package instead.
* In other cases, report issues in this repo.
Autocomplete
Make sure to put a into a otherwise web-browser's "autocomplete" feature may not be working: a user will be selecting his phone number from the list but nothing will be happening.
react-hook-form
To use this component with react-hook-form, use one of the four exported components:
`js
// "Without country select" component.
import PhoneInput from 'react-phone-number-input/react-hook-form-input'
// "Without country select" component (to pass custom metadata property).
import PhoneInput from 'react-phone-number-input/react-hook-form-input-core'
// "With country select" component.
import PhoneInputWithCountry from 'react-phone-number-input/react-hook-form'
// "With country select" component (to pass custom metadata property).
import PhoneInputWithCountry from 'react-phone-number-input/react-hook-form-core'
`
Example:
`js
// "Without country select" component.
import PhoneInput from "react-phone-number-input/react-hook-form-input"
// "With country select" component.
import PhoneInputWithCountry from "react-phone-number-input/react-hook-form"
import { useForm } from "react-hook-form"
export default function Form() {
const {
// Either pass a control property to the component
// or wrap it in a .
control,
handleSubmit
} = useForm()
return (
)
}
`
Both components accept properties:
* name — (required) Form field name.
* control — (required) The control object returned from useForm().
* rules — (optional) Validation rules in the same format as for register(). Example: {{ required: true, validate: isPossiblePhoneNumber }}.
* defaultValue — (optional) A default value could be passed directly to the component, or as part of the defaultValues parameter of useForm().
Customization
"With country select" component accepts some customization properties:
* metadata — Custom libphonenumber-js "metadata". Could be used to supply "metadata" that only contains a small subset of countries.
* labels — Custom translation "messages": country names, miscellanous labels. Example for English: react-phone-number-input/locale/en.json
* inputComponent — Custom phone number component.
* countrySelectComponent — Custom country component.
* internationalIcon — Custom "International" icon component.
* flagComponent — Custom flag icon component.
* countrySelectProps.arrowComponent — Custom "arrow" component of the default country . Renders an "arrow" "dropdown" icon. Doesn't receive any properties.
All those customization properties have their default values which are, therefore, always included in the application bundle, regardless of whether those default property values get overridden by any custom ones.
Those who'd like to exclude the default values just for metadata and labels properties could import the component from react-phone-number-input/core subpackage rather than from react-phone-number-input package.
#### countrySelectComponent
React component for the country select. See CountrySelect.js for an example.
Receives properties:
* name: string? — HTML name attribute.
* value: string? — The currently selected country code (undefined in case of "International").
* onChange(value: string?) — Updates the value (to undefined in case of "International").
* onFocus() — Is used to toggle the --focus CSS class.
* onBlur() — Is used to toggle the --focus CSS class.
* options: object[] — The list of all selectable countries (including "International") each being an object of shape { value: string?, label: string }.
* iconComponent: PropTypes.elementType — React component that renders a country icon: . If country is undefined then it renders an "International" icon.
* disabled: boolean? — HTML disabled attribute.
* readOnly: boolean? — HTML readonly attribute.
* tabIndex: (number|string)? — HTML tabIndex attribute.
* className: string — CSS class name.
#### inputComponent
A React component for the phone number input field. Is "input" by default, meaning that it renders a standard DOM .
Any custom input component implementation must use React.forwardRef() to "forward" ref to the underlying "core" component.
Receives properties:
* value: string — The formatted value.
* onChange(event: Event) — Updates the formatted value from event.target.value.
* onFocus() — Is used to toggle the --focus CSS class.
* onBlur(event: Event) — Is used to toggle the --focus CSS class.
* Other properties like type="tel" or autoComplete="tel" that should be passed through to the DOM .
#### flagComponent
Renders a country flag icon.
Receives properties:
* country: string — A two-letter ISO country code. Example: "RU".
* countryName: string — Country name. Example: "Russia".
* flags?: object — An object that contains a flag icon component for each country. Same as the flags property of the react-phone-number-input component.
* flagUrl?: string — A template for a country flag icon image URL. Same as the flagUrl property of the react-phone-number-input component.
* className: string — CSS class name.
#### internationalIcon
Renders an "International" icon. For example, the default one is a globe icon. The icon is shown instead of a country flag when the phone number is in international format (i.e. starts with a + character) but is either incomplete or doesn't belong to any known country.
Receives properties:
* title: string — ARIA label.
* aspectRatio: number — Icon aspect ratio: width / height.
* className: string — CSS class name.
CDN
To include this library directly via a tag on a page, one can use any npm CDN service, e.g. unpkg.com or jsdelivr.com
`html
`
Without country select:
`html
`
Country code
A "country code" is a two-letter ISO country code like "US", "CA", etc.
However, this library uses libphonenumber-js's variant of the "country code" term, which is rather broad and includes both the official ISO country codes and a few of unofficial "country codes". For that reason, a developer should use a "country code" returned from this library with caution in an application that only expects the official ISO "country codes" to exist. For example, such application will likely not have a label or a flag for such an unofficial "country code". In that case, a developer could manually transform an unofficial "country code" returned from this library to an official ISO country code of the most suitable "parent" country.
To check whether a certain two-letter "country code" is supported by this library, use isSupportedCountry() function.
Tests
This component comes with 100% code coverage for the core ./source/helpers directory.
To run tests:
`
npm test
`
To generate a code coverage report:
`
npm run test-coverage
`
The code coverage report can be viewed by opening ./coverage/lcov-report/index.html.
If the code coverage report is "empty" then it means that a newer version of handlebars was accidentally installed and should be reverted to handlebars@4.5.3.
The handlebars@4.5.3 workaround in devDependencies is for the test coverage to not produce empty reports:
`
Handlebars: Access has been denied to resolve the property "statements" because it is not an "own property" of its parent.
You can add a runtime option to disable the check or this warning:
See https://handlebarsjs.com/api-reference/runtime-options.html#options-to-control-prototype-access for details
``
GitHub
On March 9th, 2020, GitHub, Inc. silently banned my account (erasing all my repos, issues and comments) without any notice or explanation. Because of that, all source codes had to be promptly moved to GitLab. GitHub repo is now deprecated, and the latest source codes can be found on GitLab, which is also the place to report any issues.
License
MIT