React International Phone Input

Common errors

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

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

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

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

Warnings

• breaking 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.
  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.
• breaking 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.
  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.
• breaking 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.
  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.
• gotcha The 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.
• gotcha 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.
  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.

Install

• npm install react-international-phone npm
• yarn add react-international-phone yarn
• pnpm add react-international-phone pnpm

Imports

• PhoneInput
  wrong:

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

  correct:

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

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

  import usePhoneInput from 'react-international-phone';

  correct:

  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
  wrong:

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

  correct:

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

  Utility function for validating a phone number. Part of the validation features.
• style.css
  wrong:

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

  correct:

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

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

Quickstart

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;