Registry / communication / react-phone-number-input

react-phone-number-input

library3.4.16jsnpmunverified

react-phone-number-input is a comprehensive React component designed for entering and formatting international telephone numbers. It leverages the robust `libphonenumber-js` library internally for accurate parsing, validation, and formatting, ensuring numbers are consistently output in the E.164 format (e.g., "+12133734253"). The package is currently at version 3.4.16 and demonstrates an active release cadence, indicating ongoing development and maintenance. Its key differentiators include offering both a full-featured input with an international country select dropdown and a basic input-only variant, alongside native UI integration for country selection on mobile devices. The component effectively handles diverse country codes, various number formats, and provides clear mechanisms for controlling default country selections and managing input changes via its props.

communication web-framework serialization

npm install react-phone-number-input

package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-PHONE-NUMBER

react-phone-number-input

communicationjavascriptv3.4.16

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PhoneInput (with country select)

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

✗ 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)

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

✗ 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)

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

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

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;

Debug

Known issues

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

affects: >=3.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaThe 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'`.

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

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

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.

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.

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.

Upgrade

Version history

3.4.16latest on npm

Audit

Dependencies

reactrequiredRequired as a peer dependency for React component rendering.

react-domrequiredRequired as a peer dependency for React component rendering.

libphonenumber-jsrequiredCore runtime dependency providing phone number parsing, validation, and formatting logic.

Agent activity

21 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/react-phone-number-input ↗

homepagehttps://gitlab.com/catamphetamine/react-phone-number-input#readme ↗