React Phone Input 2

Common errors

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

  cause The stylesheet import path is incorrect or the file does not exist at the specified location.
  fix Verify the exact path for the CSS file. Ensure `react-phone-input-2` is correctly installed. Common paths are `react-phone-input-2/lib/style.css` or `react-phone-input-2/lib/material.css`.

• Warning: Failed prop type: Invalid prop `value` of type `number` supplied to `PhoneInput`, expected `string`.

  cause The `value` prop passed to `PhoneInput` is not a string, but a number (or other incorrect type).
  fix Always ensure the `value` prop is a string. If you're storing numbers, convert them to a string before passing, e.g., `value={String(myPhoneNumber)}`.

• Country flag/styles not appearing correctly, or input looks unstyled.

  cause The necessary CSS stylesheet for `react-phone-input-2` has not been imported into your application.
  fix Add `import 'react-phone-input-2/lib/style.css';` (or another theme like `material.css`) to your main application file or the component where `PhoneInput` is rendered.

• Error: Invalid hook call. Hooks can only be called inside of the body of a functional component.

  cause Attempting to use `useState` (or other React Hooks) outside of a functional React component or a custom Hook, or due to multiple React instances.
  fix Ensure `useState` is called directly within a functional component or a custom Hook. Verify that you don't have multiple versions of React installed, which can cause this error.

Warnings

• breaking This documentation is based on `react-phone-input-2` version `2.15.1`. A major version `3.x` exists and has been actively maintained and released since. Migrating to `3.x` may involve breaking changes to props, event handlers, or internal behavior. Always consult the official `3.x` changelog for migration details.
  Fix: Review the official changelog for `react-phone-input-2` v3 for specific migration steps. Test your application thoroughly after upgrading.
• gotcha It is critical to import a CSS stylesheet for the component to render correctly, including flags and proper layout. Forgetting this import will result in a functional but unstyled input. Options include `style.css`, `high-res.css`, `material.css`, `bootstrap.css`, `semantic-ui.css`, or `plain.css`.
  Fix: Add `import 'react-phone-input-2/lib/style.css';` (or your preferred theme) to your entry file or the component where `PhoneInput` is used.
• gotcha The `value` prop is expected to be a string representing the phone number (e.g., '12133734253' for `+1 (213) 373-4253`). Passing `null`, `undefined`, or other types may lead to unexpected behavior or console warnings.
  Fix: Ensure the `value` prop is always a string. Convert other types to an empty string `''` if no number is present.
• gotcha The project's README explicitly mentions 'DONATIONS / FUNDING NEEDED'. While the project is popular and maintained, this indicates potential sustainability concerns that might impact future development pace or support, especially for older versions.
  Fix: Monitor the project's GitHub repository for activity and consider contributing or sponsoring if relying heavily on the library. Factor this into long-term maintenance planning.
• gotcha When migrating from older phone number storage systems that might not include country codes, `react-phone-input-2` can incorrectly assume the first few digits of a local number as a country code. This requires careful handling of initial values.
  Fix: Utilize the `country` prop to explicitly set the default country, and potentially manipulate the initial `value` if it lacks a country code to ensure correct parsing.

Install

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

Imports

• PhoneInput
  wrong:

  const PhoneInput = require('react-phone-input-2');

  correct:

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

  Primary way to import the component in modern React (ESM). CommonJS require() is generally incorrect for React components in new projects.
• CSS Stylesheet
  wrong:

  /* Missing CSS import */

  correct:

  import 'react-phone-input-2/lib/style.css'

  Crucial for correct rendering and displaying flags. Other themes like `material.css`, `bootstrap.css`, `high-res.css` are also available in the `lib/` directory.
• PhoneInputProps

  import type { PhoneInputProps } from 'react-phone-input-2'

  Import types for TypeScript development.

Quickstart

Demonstrates a basic international phone number input with state management, country selection, auto-formatting, and a search feature in a functional React component.

import React, { useState } from 'react';
import PhoneInput from 'react-phone-input-2';
import 'react-phone-input-2/lib/style.css'; // Or 'react-phone-input-2/lib/material.css' etc.

function MyPhoneNumberInput() {
  const [phone, setPhone] = useState('');

  const handlePhoneChange = (value, country, e, formattedValue) => {
    console.log('Raw Value:', value);
    console.log('Country Object:', country);
    console.log('Event:', e);
    console.log('Formatted Value:', formattedValue);
    setPhone(value);
  };

  return (
    <div>
      <h2>Enter Your Phone Number</h2>
      <PhoneInput
        country={'us'}
        value={phone}
        onChange={handlePhoneChange}
        inputProps={{
          name: 'phone',
          required: true,
          autoFocus: true,
        }}
        placeholder="e.g. +1 702 123 4567"
        enableSearch
        disabled={false}
      />
      <p>Current Phone Number: {phone ? `+${phone}` : 'None'}</p>
    </div>
  );
}

export default MyPhoneNumberInput;