{"id":11733,"library":"react-international-phone","title":"React International Phone Input","description":"React International Phone is a lightweight and easy-to-integrate React component for handling international phone number inputs. It's currently at stable version 4.8.0, with frequent minor and patch releases to update country data, fix bugs, and add small features. Key differentiators include its small bundle size with no third-party runtime dependencies, automatic country guessing based on input, comprehensive validation utilities, and flexible customization options. It also provides a headless hook (`usePhoneInput`) for integrating with any UI library, allowing developers to maintain consistent styling while leveraging the library's core functionality for phone number formatting and country detection. It ships with TypeScript types for enhanced developer experience.","status":"active","version":"4.8.0","language":"javascript","source_language":"en","source_url":"https://github.com/ybrusentsov/react-international-phone","tags":["javascript","react","phone","input","international","format","number","tel","telephone","typescript"],"install":[{"cmd":"npm install react-international-phone","lang":"bash","label":"npm"},{"cmd":"yarn add react-international-phone","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-international-phone","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for the React component and hooks.","package":"react","optional":false}],"imports":[{"note":"Primary component for rendering the international phone input field. Requires `react-international-phone/style.css` for default styling.","wrong":"const { PhoneInput } = require('react-international-phone');","symbol":"PhoneInput","correct":"import { PhoneInput } from 'react-international-phone';"},{"note":"Headless hook for custom UI implementations. Provides state and logic for phone number handling without rendering UI elements.","wrong":"import usePhoneInput from 'react-international-phone';","symbol":"usePhoneInput","correct":"import { usePhoneInput } from 'react-international-phone';"},{"note":"Utility function for validating a phone number. Part of the validation features.","wrong":"import { validatePhone } from 'react-international-phone';","symbol":"isValidPhoneNumber","correct":"import { isValidPhoneNumber } from 'react-international-phone';"},{"note":"Imports the default CSS styles for the `PhoneInput` component. Ensure this is imported once globally or within the component scope.","wrong":"import 'react-international-phone/dist/style.css';","symbol":"style.css","correct":"import 'react-international-phone/style.css';"}],"quickstart":{"code":"import { useState } from 'react';\nimport { PhoneInput } from 'react-international-phone';\nimport 'react-international-phone/style.css';\n\nconst App = () => {\n  const [phone, setPhone] = useState('');\n\n  return (\n    <div style={{\n      display: 'flex',\n      flexDirection: 'column',\n      alignItems: 'center',\n      justifyContent: 'center',\n      minHeight: '100vh',\n      fontFamily: 'sans-serif'\n    }}>\n      <h1>Phone Number Input</h1>\n      <PhoneInput\n        defaultCountry=\"us\"\n        value={phone}\n        onChange={(phone) => setPhone(phone)}\n        inputProps={{\n          name: 'phone',\n          placeholder: 'Enter phone number',\n          autoComplete: 'tel'\n        }}\n        className=\"my-custom-phone-input\"\n      />\n      <p style={{ marginTop: '20px' }}>Current Phone: {phone || 'None'}</p>\n    </div>\n  );\n};\n\nexport default App;","lang":"typescript","description":"This quickstart demonstrates a basic international phone input component, initializes it with a default country, and updates the state on change. It also shows how to include the necessary styles and add basic input props."},"warnings":[{"fix":"Refer to the official migration guide 'Update from v3 to v4' at `https://react-international-phone-docs.vercel.app/docs/Migrations/migrate-to-v4` for detailed instructions and code examples to adapt to the new API.","message":"Migration from v3 to v4 introduced breaking changes. Key areas affected were likely API surface area changes for props or return values from hooks, and potentially internal structure modifications.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Consult the 'Update from v2 to v3' migration guide at `https://react-international-phone-docs.vercel.app/docs/Migrations/migrate-to-v3` to understand specific changes and how to update your codebase.","message":"Upgrading from v2 to v3 involved breaking changes that required adjustments to component usage or styling. This often includes prop renames, removal of deprecated features, or changes in default behavior.","severity":"breaking","affected_versions":">=3.0.0 <4.0.0"},{"fix":"Review the 'Update from v1 to v2' migration guide available at `https://react-international-phone-docs.vercel.app/docs/Migrations/migrate-to-v2` to understand the necessary modifications for a successful upgrade.","message":"The initial major version update from v1 to v2 likely included significant API changes. This could involve complete rewrites of components or hooks, and major refactors of internal logic.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Ensure you include `import 'react-international-phone/style.css';` in your entry file or the component file where `PhoneInput` is used.","message":"The default styles for the `PhoneInput` component must be explicitly imported. Forgetting this import will result in an unstyled component.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Carefully read the `usePhoneInput` documentation to understand all returned properties and methods, and manually bind them to your custom input and selector elements. Do not expect any default UI.","message":"When using the `usePhoneInput` headless hook, you are responsible for rendering all UI elements (input, country selector, flags) and connecting them to the hook's return values.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import { PhoneInput } from 'react-international-phone';`","cause":"Attempting to use `PhoneInput` with an incorrect import statement, typically `import PhoneInput from 'react-international-phone';` instead of a named import.","error":"Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports."},{"fix":"Ensure `react-international-phone/style.css` is imported and that no custom build steps are interfering with module resolution. If in SSR, check the library's SSR compatibility documentation.","cause":"This error often occurs if the country data or formatting utilities are not correctly initialized or accessed, possibly due to a missing dependency or an issue in how the library's internal data is consumed, especially in server-side rendering (SSR) environments if not configured correctly.","error":"TypeError: Cannot read properties of undefined (reading 'split') or similar errors related to country data."},{"fix":"Ensure `value` is a string (the full international number) and `onChange` accepts a string parameter, matching the `PhoneInput` component's type definitions. For example: `onChange={(phone: string) => setPhone(phone)}`.","cause":"Incorrectly typing component props in TypeScript, or providing a value that doesn't match the expected type, specifically for the `PhoneInput`'s `value` or `onChange` props.","error":"Type 'string' is not assignable to type '...'. Property 'onChange' is missing in type '...' but required in type '...'"}],"ecosystem":"npm"}