React Phone Number Input

Common errors

• Module not found: Can't resolve 'react-phone-number-input/style.css'

  cause The necessary CSS stylesheet for the component's visual styling has not been imported into the application.
  fix Add `import 'react-phone-number-input/style.css';` to a central CSS import file or directly into the component where `PhoneInput` is being used.

• TypeError: Cannot read properties of undefined (reading 'length') or similar errors related to `value` prop.

  cause The `value` prop passed to `PhoneInput` is either not provided, is `null`, or is of an incorrect type (e.g., an object instead of a string or `undefined`), leading to unexpected behavior in `libphonenumber-js`.
  fix Ensure the `value` prop is always a string in E.164 format (e.g., `"+1234567890"`), or `undefined` to represent an empty input. Always initialize the state variable managing `value` accordingly.

• React Hook "useState" cannot be called inside a class component.

  cause You are attempting to use React Hooks (such as `useState`) within a class-based React component, which is not supported by React.
  fix Refactor your component to be a functional component to utilize Hooks, or manage state using the class component's `this.state` and `this.setState` mechanisms.

Warnings

• breaking Major version 3.x introduced significant breaking changes compared to 2.x, including API alterations, styling adjustments, and internal component structure. Direct upgrades without consulting the changelog will likely result in errors.
  Fix: Review the official `CHANGELOG.md` thoroughly for specific migration steps and updated API usage when upgrading from 2.x to 3.x. Adjust component props and imports as needed.
• gotcha The `value` prop and the `onChange` callback's argument strictly use the E.164 format string (e.g., '+12133734253') for valid numbers. For an empty or cleared input, `onChange` will return `undefined`, not `null` or an empty string. Misinterpreting `undefined` can lead to incorrect state management or UI behavior.
  Fix: Ensure your state management and validation logic explicitly checks for `undefined` when expecting an empty or cleared input value. Always initialize state for `value` as `undefined` or an E.164 string.
• gotcha The default `PhoneInput` export includes the country select dropdown. If you only require a basic phone number input field without this feature (e.g., for custom UI or smaller bundle size), you must use the specific import `from 'react-phone-number-input/input'`. Using the default export unnecessarily can increase bundle size.
  Fix: For a basic input without country selection, always import `PhoneInput from 'react-phone-number-input/input'`. For the full component, use `import PhoneInput from 'react-phone-number-input'` or `import { PhoneInputWithCountrySelect } from 'react-phone-number-input'`.
• gotcha The underlying `libphonenumber-js` library can significantly increase your application's bundle size if all locale data for every country is loaded. This can impact initial load performance, especially for web applications.
  Fix: Implement selective data loading for `libphonenumber-js`. Consider importing only specific country data or using smaller data subsets (e.g., `import 'libphonenumber-js/min'` for minimal data, or `import 'libphonenumber-js/max'` for more common data without all edge cases), or dynamic imports for less frequently used data.

Install

• npm install react-phone-number-input npm
• yarn add react-phone-number-input yarn
• pnpm add react-phone-number-input pnpm

Imports

• PhoneInput (with country select)
  wrong:

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

  correct:

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

  This is the default export and provides the phone number input field integrated with a country select dropdown. For the basic input without a country select, a different import path is required.
• PhoneInput (basic input)
  wrong:

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

  correct:

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

  This variant provides only the phone number input field without the country select dropdown. It's useful for reducing bundle size if the dropdown UI is not needed or custom-implemented.
• PhoneInputWithCountrySelect (memoized)
  wrong:

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

  correct:

  import { PhoneInputWithCountrySelect } from 'react-phone-number-input'

  A named export that is a `React.memo`-wrapped version of the default `PhoneInput` (with country select), offering performance optimizations by preventing unnecessary re-renders.
• CSS styles

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

  This stylesheet is essential for the correct visual appearance and basic layout of both `PhoneInput` variants. It should be imported once in your application.

Quickstart

This quickstart demonstrates a functional React component using the default `PhoneInput` (with country select). It shows how to manage the input's value using React state and displays the resulting E.164 formatted number, including necessary CSS import and default country setting.

import React, { useState } from 'react';
import 'react-phone-number-input/style.css';
import PhoneInput from 'react-phone-number-input';

function App() {
  const [value, setValue] = useState();

  // `value` will be the parsed phone number in E.164 format (e.g., "+12133734253").
  // For an empty input, `value` will be `undefined`.
  return (
    <div style={{ maxWidth: '400px', margin: '50px auto', fontFamily: 'sans-serif' }}>
      <h1>International Phone Input</h1>
      <p>Enter your phone number below:</p>
      <PhoneInput
        placeholder="Enter phone number"
        value={value}
        onChange={setValue}
        defaultCountry="US"
        international
        countryCallingCodeEditable={false}
      />
      {value && <p>Parsed E.164 Value: <code>{value}</code></p>}
      {!value && <p>Input is currently empty or invalid.</p>}
    </div>
  );
}

export default App;