npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2020 – Pkg Stats / Ryan Hefner

react-phone-number-input

v3.1.3

Published

Telephone number input React component

Downloads

376,128

Readme

react-phone-number-input

npm version npm downloads

International phone number <input/> for React.

See Demo

Install

npm install react-phone-number-input --save

If you're not using a bundler then use a standalone version from a CDN.

The component uses libphonenumber-js for phone number parsing and formatting.

Use

The 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.

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 (
    <PhoneInput
      placeholder="Enter phone number"
      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".

All unknown properties will be passed through to the phone number <input/> component.

To set a default country, pass a defaultCountry property. Example: <PhoneInput defaultCountry="US" .../>.

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, and :focus state is styled via .PhoneInput--focus CSS class.

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:

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.

<head>
  <link rel="stylesheet" href="/css/react-phone-number-input/style.css"/>
</head>

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 phone number <input/>.

import PhoneInput from 'react-phone-number-input/input'

function Example() {
  // `value` will be the parsed phone number in E.164 format.
  // Example: "+12133734253".
  const [value, setValue] = useState()
  // If `country` property is not passed
  // then "International" format is used.
  // Otherwise, "National" format is used.
  return (
    <PhoneInput
      country="US"
      value={value}
      onChange={setValue} />
  )
}

Doesn't require any CSS.

Receives properties:

  • country: string? — If country is specified then the phone number can only be input in "national" (not "international") format, and will be parsed as a phone number belonging to the country. Example: country="US".

  • international: 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 (+1 when country is US) is not included in the input field: that could be changed by passing withCountryCallingCode property (see below). So, if country is US and international property is not passed then the phone number can only be input in the "national" format for US ((213) 373-4253). But if country is "US" and international property is true then the phone number can only be input in the "international" format for US (213 373 4253) without the "country calling code" part (+1). This could be used for implementing phone number input components that show "country calling code" part before the input field and then the user can fill in the rest of their phone number digits in the input field.

  • 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 (+1 when country is US) is not included in the input field. To change that, pass withCountryCallingCode property, and it will include the "country calling code" part in the input field. See the demo for an example.

  • defaultCountry: string? — If defaultCountry is specified then the phone number can be input both in "international" format and "national" format. A phone number that's being input in "national" format will be parsed as a phone number belonging to the defaultCountry. Example: defaultCountry="US".

  • If neither country nor defaultCountry are specified then the phone number can only be input in "international" format.

  • value: string? — Phone number value. Examples: undefined, "+12133734253".

  • onChange(value: string?) — Updates the value.

  • inputComponent: component? — A custom <input/> component can be passed. In that case, it must be a React.forwardRef() to the actual <input/>.

  • smartCaret: boolean? — By default, the <input/> uses "smart" caret positioning. To turn that behavior off one can pass smartCaret={false} property.

  • useNationalFormatForDefaultCountryValue: boolean? — When defaultCountry is defined and the initial value corresponds to defaultCountry, then the value will be formatted as a national phone number by default. To format the initial value of defaultCountry as an international number instead set useNationalFormatForDefaultCountryValue property to false.

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 <select/> could be used in conjunction with the "without country select" <input/> described above.

import PropTypes from 'prop-types'
import { getCountries, getCountryCallingCode } from 'react-phone-number-input/input'

const CountrySelect = ({ value, onChange, labels, ...rest }) => (
  <select
    {...rest}
    value={value}
    onChange={event => onChange(event.target.value || undefined)}>
    <option value="">
      {labels['ZZ']}
    </option>
    {getCountries().map((country) => (
      <option key={country} value={country}>
        {labels[country]} +{getCountryCallingCode(country)}
      </option>
    ))}
  </select>
)

CountrySelect.propTypes = {
  value: PropTypes.string,
  onChange: PropTypes.func.isRequired,
  labels: PropTypes.objectOf(PropTypes.string).isRequired
}

Use:

import PhoneInput from 'react-phone-number-input/input'
import en from 'react-phone-number-input/locale/en.json'
import CountrySelect from './CountrySelect'

function Example() {
  const [country, setCountry] = useState('US')
  const [value, setValue] = useState()
  return (
    <div>
      <CountrySelect
        labels={en}
        value={country}
        onChange={setCountry}/>
      <PhoneInput
        country={country}
        value={value}
        onChange={setValue}/>
    </div>
  )
}

React Native

This library is shipped with an experimental React Native component. See the feedback thread.

import React, { useState } from 'react'
import PhoneInput from 'react-phone-number-input/react-native-input'

function Example() {
  const [value, setValue] = useState()
  return (
    <PhoneInput
      style={...}
      defaultCountry="US"
      value={value}
      onChange={setValue} />
  )
}

Utility

This package exports several utility functions.

formatPhoneNumber(value: string): string

Formats value as a "local" phone number.

import { formatPhoneNumber } from 'react-phone-number-input'
formatPhoneNumber('+12133734253') === '(213) 373-4253'

formatPhoneNumberIntl(value: string): string

Formats value as an "international" phone number.

import { formatPhoneNumberIntl } from 'react-phone-number-input'
formatPhoneNumberIntl('+12133734253') === '+1 213 373 4253'

isPossiblePhoneNumber(value: string): boolean

Checks if the phone number is "possible". Only checks the phone number length, doesn't check the number digits against any regular expressions like isValidPhoneNumber() does.

import { isPossiblePhoneNumber } from 'react-phone-number-input'
isPossiblePhoneNumber('+12133734253') === true
isPossiblePhoneNumber('+19999999999') === true

isValidPhoneNumber(value: string): boolean

Validates a phone number value.

import { isValidPhoneNumber } from 'react-phone-number-input'
isValidPhoneNumber('+12133734253') === true
isValidPhoneNumber('+19999999999') === false

By default the component uses min "metadata" which results in less strict validation compared to max or mobile.

I personally don't use strict phone number validation in my projects because telephone numbering plans sometimes change and so validation rules can change too which means that isValidPhoneNumber() function may become outdated if a website isn't re-deployed regularly. If it was required to validate a phone number being input by a user, then I'd personally use something like isPossiblePhoneNumber() that just validates phone number length.

parsePhoneNumber(input: string): PhoneNumber?

Parses a PhoneNumber object from a string. This is simply an alias for parsePhoneNumberFromString() from libphonenumber-js. Can be used to get country from value.

import { parsePhoneNumber } from 'react-phone-number-input'
const phoneNumber = parsePhoneNumber('+12133734253')
if (phoneNumber) {
  phoneNumber.country === 'US'
}

getCountryCallingCode(country: string): string

This is simply an alias for getCountryCallingCode() from libphonenumber-js.

import { getCountryCallingCode } from 'react-phone-number-input'
getCountryCallingCode('US') === '1'

Flags URL

By default, all flags are linked from country-flag-icons's GitHub pages website as <img src="..."/>s. Any other flag icons could be used instead by passing a custom flagUrl property (which is "https://catamphetamine.gitlab.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:

:root {
  --PhoneInputCountryFlag-aspectRatio: 1.333;
}
<PhoneInput flagUrl="https://flag.pk/flags/4x3/{xx}.svg" .../>

A sidenote: flagpack doesn't have AC and TA flags, so the flag.pk website URL can't be used directly.

Including all flags

Linking flag icons as external <img/>s is only done to reduce the overall bundle size, because including all country flags in the code as inline <svg/>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:

import PhoneInput from 'react-phone-number-input'
import flags from 'react-phone-number-input/flags'

<PhoneInput flags={flags} .../>

Localization

Language translations can be applied using the labels property. This component comes pre-packaged with several translations. Submit pull requests for adding new language translations.

Country names can be copy-pasted from github.com/umpirsky/country-list.

JSON.stringify(
  Object.keys(countries).sort()
    .reduce((all, country) => ({ ...all, [country]: countries[country] }), {}),
  null,
  '\t'
)

Also note that a country names list generated from umpirsky/country-list won't include Ascension Island (AC) and Tristan da Cunha (TA) — they will need to be added manually.

The labels format is:

{
  // Can be used as a label for country input.
  // Country `<select/>` uses this as its default `aria-label`.
  "country": "Phone number country",
  // Can be used as a label for phone number input.
  "phone": "Phone",
  // Can be used as a label for phone number extension input.
  "ext": "ext.",
  // Country names.
  "AB": "Abkhazia",
  "AC": "Ascension Island",
  ...,
  "ZZ": "International"
}

An example of using translated labels:

import ru from 'react-phone-number-input/locale/ru'

<PhoneInput ... labels={ru}/>

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 140 kilobytes in size (libphonenumber-js/metadata.full.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 75 kilobytes 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 follow the bug reporting instructions in libphonenumber-js repo. Otherwise report issues in this repo.

Autocomplete

Make sure to put a <PhoneInput/> into a <form/> 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.

Customizing

The <PhoneInput/> component accepts some customization properties:

  • inputComponent — Custom phone number <input/> component.

  • countrySelectComponent — Custom country <select/> component.

  • metadata — Custom libphonenumber-js "metadata".

  • labels — Custom translation (including country names).

  • internationalIcon — Custom "International" icon.

  • flagComponent — Custom flag icon component.

  • countrySelectProps.arrowComponent — Custom arrow component of the default country <select/>.

All these customization properties have their default values: min metadata, English labels, default country <select/> component. If some of those default values are not used, and the developer wants to reduce the bundle size a tiny bit, then they can use the /core export instead of the default export to import a <PhoneInput/> component that doesn't include any of the aforementioned default properties.

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.
  • onChange(value: string?) — Updates the value.
  • 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: <Icon country={value}/>. If country is undefined then it renders an "International" icon.
  • disabled: boolean? — HTML disabled attribute.
  • tabIndex: (number|string)? — HTML tabIndex attribute.
  • className: string — CSS class name.

inputComponent

React component for the phone number input field. Is "input" by default meaning that it renders a standard DOM <input/>.

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 <input/>.

Must also use React.forwardRef() to "forward" ref to the <input/>.

CDN

One can use any npm CDN service, e.g. unpkg.com or jsdelivr.net

<!-- Default ("min" metadata). -->
<script src="https://unpkg.com/[email protected]/bundle/react-phone-number-input.js"></script>

<!-- Or "max" metadata. -->
<script src="https://unpkg.com/[email protected]/bundle/react-phone-number-input-max.js"></script>

<!-- Or "mobile" metadata. -->
<script src="https://unpkg.com/[email protected]/bundle/react-phone-number-input-mobile.js"></script>

<!-- Styles for the component. -->
<!-- Internet Explorer requires transpiling CSS variables. -->
<link rel="stylesheet" href="https://unpkg.com/[email protected]/bundle/style.css"/>

<script>
  var PhoneInput = window.PhoneInput.default
</script>

Without country select:

<!-- Without country `<select/>` ("min" metadata). -->
<script src="https://unpkg.com/[email protected]/bundle/react-phone-number-input-input.js"></script>

<script>
  var PhoneInput = window.PhoneInput.default
</script>

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