react-phone-number-input

The package allows you to choose between different metadata sets to balance phone number validation capabilities against bundle size. The choice depends on whether you need strict validation or phone number type detection (e.g., distinguishing 'mobile' from 'fixed line').

Metadata Options

• min (Default): Smallest set (~80KB). Use when you only need basic length validation via isPossiblePhoneNumber() and do not need strict digit validation or type detection.
• max: Complete set (~145KB). Use when you need strict validation via isValidPhoneNumber() or need to detect phone number types.
• mobile: Mobile-only set (~95KB). Use when you want max capabilities but only intend to accept mobile numbers. It can handle non-mobile numbers, but validation might return false or fail to determine the type.
• custom: Advanced. Use when you want to generate your own metadata (via libphonenumber-js) to support only specific countries and minimize bundle size further.

The library provides dedicated components for seamless integration with react-hook-form. You can pass the control object directly to the component or wrap your form in a <FormProvider/>.

// "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 {
    control,
    handleSubmit
  } = useForm()

  return (
    <form onSubmit={handleSubmit(...)}>
      <PhoneInput
        name="phoneInput"
        control={control}
        rules={{ required: true }} />

      <PhoneInputWithCountry
        name="phoneInputWithCountrySelect"
        control={control}
        rules={{ required: true }} />

      <button type="submit">
        Submit
      </button>
    </form>
  )
}

The PhoneInput component (imported from react-phone-number-input) is the most feature-complete variant. It includes a country selector with flags and labels on the left side of the input field.

Requirements:

• You must import the CSS styles: import 'react-phone-number-input/style.css'.

Core Props:

• value: The phone number in E.164 format (e.g., "+12133734253"). Falsy values (undefined, null, or "") are treated as no value.
• onChange(value): A callback function called when the user types or clears the input. The argument is the parsed phone number in E.164 format, or undefined if the field is cleared.
• defaultCountry (optional): A two-letter country code (e.g., "US") to set the initial country selection.
• onCountryChange (optional): A callback function called when the user selects a different country, receiving the new country code as an argument.
• Any other standard HTML <input> props (like placeholder) are passed through to the underlying input element.

// CSS styles
import 'react-phone-number-input/style.css'

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

function Example() {
  const [value, setValue] = useState()
  return (
    <PhoneInput
      placeholder="Enter phone number"
      value={value}
      onChange={setValue}
    />
  )
}

You can build a custom country selection UI by using the exported getCountries() and getCountryCallingCode(country) functions alongside the PhoneInput/input component. This allows you to decouple the country selection from the phone number input field.

import PropTypes from 'prop-types'
import { getCountries, getCountryCallingCode } from 'react-phone-number-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
}

The <PhoneInput/> component (with country select) supports several customization properties to override default behavior or appearance.

Note on Bundle Size: All default values are included in your application bundle by default. To exclude default metadata and labels to save space, import the component from the react-phone-number-input/core subpackage instead of the main react-phone-number-input package.

Available Customization Props:

• metadata: Custom libphonenumber-js metadata (e.g., to limit the subset of supported countries).
• labels: Custom translation messages for country names and other labels.
• inputComponent: Custom phone number <input/> component.
• countrySelectComponent: Custom country <select/> component.
• internationalIcon: Custom icon component for the 'International' state.
• flagComponent: Custom flag icon component.
• countrySelectProps.arrowComponent: Custom arrow/dropdown icon for the country selector.