Registry / web-framework / react-international-phone

react-international-phone

library4.8.0jsnpmunverified

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.

web-framework

npm install react-international-phone

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-INTERNATIONA

react-international-phone

web-frameworkjavascriptv4.8.0

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

✓ import { PhoneInput } from 'react-international-phone';

✗ const { PhoneInput } = require('react-international-phone');

Primary component for rendering the international phone input field. Requires `react-international-phone/style.css` for default styling.

usePhoneInput

✓ import { usePhoneInput } from 'react-international-phone';

✗ import usePhoneInput from 'react-international-phone';

Headless hook for custom UI implementations. Provides state and logic for phone number handling without rendering UI elements.

isValidPhoneNumber

✓ import { isValidPhoneNumber } from 'react-international-phone';

✗ import { validatePhone } from 'react-international-phone';

Utility function for validating a phone number. Part of the validation features.

style.css

✓ import 'react-international-phone/style.css';

✗ import 'react-international-phone/dist/style.css';

Imports the default CSS styles for the `PhoneInput` component. Ensure this is imported once globally or within the component scope.

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.

import { useState } from 'react'; import { PhoneInput } from 'react-international-phone'; import 'react-international-phone/style.css'; const App = () => { const [phone, setPhone] = useState(''); return ( <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', minHeight: '100vh', fontFamily: 'sans-serif' }}> <h1>Phone Number Input</h1> <PhoneInput defaultCountry="us" value={phone} onChange={(phone) => setPhone(phone)} inputProps={{ name: 'phone', placeholder: 'Enter phone number', autoComplete: 'tel' }} className="my-custom-phone-input" /> <p style={{ marginTop: '20px' }}>Current Phone: {phone || 'None'}</p> </div> ); }; export default App;

Debug

Known issues

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

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.

affects: >=4.0.0

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

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.

affects: >=3.0.0 <4.0.0

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

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.

affects: >=2.0.0 <3.0.0

gotchaThe default styles for the `PhoneInput` component must be explicitly imported. Forgetting this import will result in an unstyled component.

fix

Ensure you include `import 'react-international-phone/style.css';` in your entry file or the component file where `PhoneInput` is used.

affects: >=1.0.0

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

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.

affects: >=1.0.0

Errors

Common errors & fixes

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.

Attempting to use `PhoneInput` with an incorrect import statement, typically `import PhoneInput from 'react-international-phone';` instead of a named import.

fix

Change your import statement to `import { PhoneInput } from 'react-international-phone';`

TypeError: Cannot read properties of undefined (reading 'split') or similar errors related to country data.

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.

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.

Type 'string' is not assignable to type '...'. Property 'onChange' is missing in type '...' but required in type '...'

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.

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)}`.

Upgrade

Version history

4.8.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency required for the React component and hooks.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/ybrusentsov/react-international-phone ↗

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

homepagehttps://react-international-phone.com ↗