{"id":15206,"library":"react-phone-number-input","title":"React Phone Number Input","description":"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.","status":"active","version":"3.4.16","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","react","phone","number","input","telephone","international","typescript"],"install":[{"cmd":"npm install react-phone-number-input","lang":"bash","label":"npm"},{"cmd":"yarn add react-phone-number-input","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-phone-number-input","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for React component rendering.","package":"react","optional":false},{"reason":"Required as a peer dependency for React component rendering.","package":"react-dom","optional":false},{"reason":"Core runtime dependency providing phone number parsing, validation, and formatting logic.","package":"libphonenumber-js","optional":false}],"imports":[{"note":"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.","wrong":"import { PhoneInput } from 'react-phone-number-input'","symbol":"PhoneInput (with country select)","correct":"import PhoneInput from 'react-phone-number-input'"},{"note":"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.","wrong":"import { PhoneInput } } from 'react-phone-number-input/input'","symbol":"PhoneInput (basic input)","correct":"import PhoneInput from 'react-phone-number-input/input'"},{"note":"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.","wrong":"import PhoneInputWithCountrySelect from 'react-phone-number-input'","symbol":"PhoneInputWithCountrySelect (memoized)","correct":"import { PhoneInputWithCountrySelect } from 'react-phone-number-input'"},{"note":"This stylesheet is essential for the correct visual appearance and basic layout of both `PhoneInput` variants. It should be imported once in your application.","symbol":"CSS styles","correct":"import 'react-phone-number-input/style.css'"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport 'react-phone-number-input/style.css';\nimport PhoneInput from 'react-phone-number-input';\n\nfunction App() {\n  const [value, setValue] = useState();\n\n  // `value` will be the parsed phone number in E.164 format (e.g., \"+12133734253\").\n  // For an empty input, `value` will be `undefined`.\n  return (\n    <div style={{ maxWidth: '400px', margin: '50px auto', fontFamily: 'sans-serif' }}>\n      <h1>International Phone Input</h1>\n      <p>Enter your phone number below:</p>\n      <PhoneInput\n        placeholder=\"Enter phone number\"\n        value={value}\n        onChange={setValue}\n        defaultCountry=\"US\"\n        international\n        countryCallingCodeEditable={false}\n      />\n      {value && <p>Parsed E.164 Value: <code>{value}</code></p>}\n      {!value && <p>Input is currently empty or invalid.</p>}\n    </div>\n  );\n}\n\nexport default App;","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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'`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The necessary CSS stylesheet for the component's visual styling has not been imported into the application.","error":"Module not found: Can't resolve 'react-phone-number-input/style.css'"},{"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.","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`.","error":"TypeError: Cannot read properties of undefined (reading 'length') or similar errors related to `value` prop."},{"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.","cause":"You are attempting to use React Hooks (such as `useState`) within a class-based React component, which is not supported by React.","error":"React Hook \"useState\" cannot be called inside a class component."}],"ecosystem":"npm"}