React International Phone

https://github.com/ybrusentsov/react-international-phone
Admin
A lightweight and customizable international phone input component for React with country guessing,...
Tokens:20,200
Snippets:122
Trust Score:8.9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install react-international-phone

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/README.md

Command to install the library via npm.

```bash
npm i react-international-phone
```

--------------------------------

### Basic Example with Custom Flags

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/04-CustomCountryFlags/index.md

A complete example demonstrating how to set up the PhoneInput component with custom country flags and filter the available countries.

```APIDOC
## Basic Example with Custom Flags

### Description

This example shows a full implementation of the `PhoneInput` component using custom flags. It includes filtering the default countries to only show those with custom flags and setting custom flag dimensions.

### Method

Component Usage

### Endpoint

N/A (Component Usage)

### Parameters

#### Component Props

- **countries** (Array<string>) - Required - A filtered list of countries to be displayed in the dropdown. Derived from `defaultCountries` and `customFlags`.
- **flags** (Array<{ iso2: string, src: string }>) - Required - The array of custom flag objects.
- **style** (object) - Optional - CSS-in-JS object to apply styles, including flag dimensions via CSS variables.
- **value** (string) - Required - The current phone number value.
- **onChange** (function) - Required - Callback function when the phone number changes.
- **defaultCountry** (string) - Optional - The default country code to pre-select.
- **placeholder** (string) - Optional - Placeholder text for the input field.

### Request Example

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

import React, { useState } from 'react';
import {
  defaultCountries,
  parseCountry,
  PhoneInput,
} from 'react-international-phone';

const customFlags = [
  { iso2: 'ua', src: '/flags/ua.svg' },
  { iso2: 'fr', src: '/flags/fr.svg' },
  { iso2: 'jp', src: '/flags/jp.svg' },
  { iso2: 'pl', src: '/flags/pl.svg' },
];

const countries = defaultCountries.filter((c) => {
  const country = parseCountry(c);
  return customFlags.map((f) => f.iso2).includes(country.iso2);
});

const App = () => {
  const [phone, setPhone] = useState('');

  return (
    <PhoneInput
      countries={countries}
      flags={customFlags}
      style={{
        '--react-international-phone-flag-width': '24px',
        '--react-international-phone-flag-height': '24px',
      }}
      value={phone}
      onChange={setPhone}
      defaultCountry="jp"
      placeholder="Phone number"
    />
  );
};

export default App;
```

### Response

This example demonstrates component usage and does not have a direct API response. The `PhoneInput` component renders with the specified custom flags and styles.
```

--------------------------------

### Install react-international-phone

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/01-getting-started.md

Install the react-international-phone library using your preferred package manager. This is the first step to integrate international phone number input into your React application.

```shell
npm install react-international-phone
```

```shell
yarn add react-international-phone
```

```shell
pnpm add react-international-phone
```

--------------------------------

### Use FlagImage Component

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/03-Subcomponents-API/04-FlagImage.md

Shows a basic example of how to use the FlagImage component by providing the 'iso2' and 'size' properties. The 'iso2' property specifies the country code, and 'size' controls the dimensions of the flag.

```tsx
<FlagImage iso2="ua" size="30px" />
```

--------------------------------

### Full Configuration with Custom Flags and Styling

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/04-CustomCountryFlags/index.md

A complete example showing how to filter countries and apply custom styles to flags using CSS variables. It demonstrates the integration of the 'flags' prop alongside standard component props like 'value', 'onChange', and 'defaultCountry'.

```tsx
import 'react-international-phone/style.css';
import React, { useState } from 'react';
import { defaultCountries, parseCountry, PhoneInput } from 'react-international-phone';

const customFlags = [
  { iso2: 'ua', src: '/flags/ua.svg' },
  { iso2: 'fr', src: '/flags/fr.svg' },
  { iso2: 'jp', src: '/flags/jp.svg' },
  { iso2: 'pl', src: '/flags/pl.svg' },
];

const countries = defaultCountries.filter((c) => {
  const country = parseCountry(c);
  return customFlags.map((f) => f.iso2).includes(country.iso2);
});

const App = () => {
  const [phone, setPhone] = useState('');
  return (
    <PhoneInput
      countries={countries}
      flags={customFlags}
      style={{
        '--react-international-phone-flag-width': '24px',
        '--react-international-phone-flag-height': '24px',
      } as React.CSSProperties}
      value={phone}
      onChange={setPhone}
      defaultCountry="jp"
      placeholder="Phone number"
    />
  );
};
```

--------------------------------

### Use DialCodePreview Component

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/03-Subcomponents-API/03-DialCodePreview.md

Shows a basic example of how to use the DialCodePreview component. It requires the 'dialCode' and 'prefix' props to display the country dial code. Optional style and className props can be used for customization.

```tsx
<DialCodePreview dialCode="1" prefix="+" />
```

--------------------------------

### ParsedCountry Object Example

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/01-PhoneInput.md

Provides an example of a 'ParsedCountry' object, illustrating the data structure and typical values for country information.

```typescript
{
  name: 'Ukraine';
  iso2: 'ua';
  dialCode: '380';
  format: '(..) ... .. ..';
  priority: undefined;
  areaCodes: undefined;
}
```

--------------------------------

### Basic PhoneInput Usage

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/01-PhoneInput.md

Shows a basic example of how to use the PhoneInput component in a React application. It includes setting a default country and handling phone number changes via the onChange callback.

```tsx
<PhoneInput
  defaultCountry="ua"
  value={phone}
  onChange={(phone) => setPhone(phone)}
/>
```

--------------------------------

### PhoneInput Component with Default Country

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/01-PhoneInput.md

A minimal example of the PhoneInput component, demonstrating its use with only the defaultCountry prop specified. This is useful for quickly integrating a phone input field with a pre-selected country.

```tsx
<PhoneInput defaultCountry="ua" />
```

--------------------------------

### Implement Phone Validation in React Form

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/03-PhoneValidation/index.md

A complete React component example demonstrating how to integrate the validation utility with the PhoneInput component. It includes real-time validation feedback and disables the submit button if the input is invalid.

```tsx
import { PhoneNumberUtil } from 'google-libphonenumber';
import React, { useState } from 'react';
import { PhoneInput } from 'react-international-phone';
import 'react-international-phone/style.css';

const phoneUtil = PhoneNumberUtil.getInstance();

const isPhoneValid = (phone: string) => {
  try {
    return phoneUtil.isValidNumber(phoneUtil.parseAndKeepRawInput(phone));
  } catch (error) {
    return false;
  }
};

const App = () => {
  const [phone, setPhone] = useState('');
  const isValid = isPhoneValid(phone);

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        alert(`Submitted phone: ${phone}`);
      }}
    >
      <PhoneInput
        defaultCountry="ua"
        value={phone}
        onChange={(phone) => setPhone(phone)}
      />

      {!isValid && <div style={{ color: 'red' }}>Phone is not valid</div>}

      <button
        disabled={!isValid}
        type="submit"
      >
        Submit
      </button>
    </form>
  );
};
```

--------------------------------

### Configure ESLint for Type-Aware Linting in JavaScript

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/examples/basic-example/README.md

This JavaScript code snippet shows how to configure ESLint's parserOptions to enable type-aware lint rules. It specifies the ECMAScript version, module type, project configuration files (tsconfig.json and tsconfig.node.json), and the root directory for TypeScript configuration. This setup is recommended for production applications to improve code quality.

```javascript
parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    project: ['./tsconfig.json', './tsconfig.node.json'],
    tsconfigRootDir: __dirname,
   }
```

--------------------------------

### Customize Styling with CSS Variables in react-international-phone

Source: https://context7.com/ybrusentsov/react-international-phone/llms.txt

Demonstrates how to deeply customize the appearance of the PhoneInput component using CSS variables and class names. The example shows how to modify height, background color, text color, border radius, and more via inline styles and class props. It also illustrates how to style specific parts like the country selector button and dropdown.

```tsx
import { PhoneInput } from 'react-international-phone';
import 'react-international-phone/style.css';

function StyledPhoneInput() {
  return (
    <PhoneInput
      defaultCountry="us"
      style={{
        '--react-international-phone-height': '44px',
        '--react-international-phone-background-color': '#f8f9fa',
        '--react-international-phone-text-color': '#333',
        '--react-international-phone-font-size': '16px',
        '--react-international-phone-border-radius': '8px',
        '--react-international-phone-border-color': '#dee2e6',
        '--react-international-phone-disabled-background-color': '#e9ecef',
        '--react-international-phone-disabled-text-color': '#6c757d',
        '--react-international-phone-country-selector-background-color-hover': '#e9ecef',
      } as React.CSSProperties}
      className="custom-phone-input"
      inputClassName="custom-input-field"
      inputStyle={{ fontFamily: 'monospace' }}
      countrySelectorStyleProps={{
        buttonClassName: 'custom-country-button',
        dropdownStyleProps: {
          className: 'custom-dropdown',
          listItemClassName: 'custom-dropdown-item',
        },
      }}
    />
  );
}
```

--------------------------------

### FlagImage Component Usage

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/03-Subcomponents-API/04-FlagImage.md

Demonstrates how to import and use the FlagImage component with basic properties.

```APIDOC
## FlagImage Component

### Description

The `FlagImage` component is used for rendering country flags. It is utilized within the `CountrySelector` and `CountrySelectorDropdown` components.

### Usage

Import the component and use it by providing the `iso2` code and optionally `size`.

### Import
```tsx
import { FlagImage } from 'react-international-phone';
```

### Example
```tsx
<FlagImage iso2="ua" size="30px" />
```

### Properties

#### `iso2` (string) - Required

- The ISO 3166-1 alpha-2 code of the country flag to display.

#### `src` (string) - Optional

- A custom source URL for the flag image. Defaults to `undefined`.

#### `protocol` ( "http" | "https" ) - Optional

- The protocol to use when fetching flags from the twemoji CDN. Defaults to `"https"`.

#### `disableLazyLoading` (boolean) - Optional

- Disables lazy loading for the flag image. If set to `true`, the `loading="lazy"` attribute will not be applied.

### Style Properties

- **`size`** (`CSSProperties['width']`) - Sets the width and height of the flag image.
- **`style`** (`CSSProperties`) - Allows for custom inline styles.
- **`className`** (`string`) - Allows for custom CSS classes.

### CSS Variables

- **`--react-international-phone-flag-width`**: Default value `24px`.
- **`--react-international-phone-flag-height`**: Default value `24px`.
```

--------------------------------

### usePhoneInput Hook Usage

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/04-Advanced-Usage/01-usePhoneInput.md

Demonstrates the basic usage of the usePhoneInput hook, showing how to destructure its returned values and integrate them with an input component.

```APIDOC
## usePhoneInput Hook Usage

### Description
This snippet shows how to import and use the `usePhoneInput` hook. It illustrates destructuring the hook's return values like `inputValue`, `phone`, `country`, `setCountry`, `handlePhoneValueChange`, and `inputRef` for managing phone input in a React component.

### Method
`usePhoneInput` (Hook)

### Endpoint
N/A (This is a React Hook)

### Parameters
#### Hook Arguments
- **`value`** (string) - Optional - The initial phone value. Defaults to `""`.
- **`onChange`** (function) - Optional - Callback function triggered on phone value change. Receives an object with `phone`, `inputValue`, and `country`.
- **`defaultCountry`** (string) - Optional - The default country ISO2 code. Defaults to `"us"`.
- **`countries`** (array) - Optional - An array of country data objects to be used. Defaults to `defaultCountries`.
- **`prefix`** (string) - Optional - The prefix for the phone value. Defaults to `"+"`.
- **`defaultMask`** (string) - Optional - A default mask applied to countries without a specific mask. Defaults to `"............"`.
- **`charAfterDialCode`** (string) - Optional - Character displayed after the dial code. Defaults to a non-breaking space (`&nbsp;`).
- **`historySaveDebounceMS`** (number) - Optional - Debounce time in milliseconds for saving history. Defaults to `200`.
- **`disableCountryGuess`** (boolean) - Optional - Disables automatic country guessing. Defaults to `false`.
- **`disableDialCodePrefill`** (boolean) - Optional - Disables prefilling the dial code for empty values. Defaults to `false`.
- **`forceDialCode`** (boolean) - Optional - Ensures the dial code is always displayed. Defaults to `false`.
- **`disableDialCodeAndPrefix`** (boolean) - Optional - Hides the dial code and prefix from the displayed phone value. Defaults to `false`.
- **`disableFormatting`** (boolean) - Optional - Disables all phone number formatting. Defaults to `false`.
- **`allowMaskOverflow`** (boolean) - Optional - Allows the input to exceed the mask length. Defaults to `false`.
- **`inputRef`** (React.MutableRefObject) - Optional - A ref object for the input element.

### Returned Values
- **`inputValue`** (string) - The formatted phone string to be rendered in the input.
- **`phone`** (string) - The phone number in E.164 format.
- **`handlePhoneValueChange`** (function) - The change handler for the input component.
- **`inputRef`** (React.RefObject) - A ref object for the input component, handling caret position, focus, and undo/redo.
- **`country`** (object) - The current country object.
- **`setCountry`** (function) - A function to programmatically set the country.

### Request Example
```javascript
// import { usePhoneInput } from 'react-international-phone';

const { 
  inputValue,
  phone,
  country,
  setCountry,
  handlePhoneValueChange,
  inputRef,
} = usePhoneInput({
  defaultCountry: 'us',
  value: '+1 (234)',
  onChange: ({ phone, inputValue, country }) => {
    // Handle changes here
  },
});
```

### Response
N/A (This is a hook, not an API endpoint)

### Response Example
N/A
```

--------------------------------

### Get Active Formatting Mask - react-international-phone

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/05-GetActiveCountryMask.md

Demonstrates how to get the active country's formatting mask using `getActiveFormattingMask`. This function requires the current phone number and country object. It's crucial to use this mask for formatting instead of the raw `country.format` value, especially for dynamic masks.

```tsx
import { PhoneInput, getActiveFormattingMask } from 'react-international-phone';
import { useState } from 'react';

const App = () => {
  const [phone, setPhone] = useState('');

  return (
    <PhoneInput
      value={phone}
      onChange={(phone, { country }) => {
        setPhone(phone);
        const mask = getActiveFormattingMask({ phone, country });
        // use formatting mask for your purposes
      }})
    />
  )
}
```

--------------------------------

### Get Active Formatting Mask

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/05-GetActiveCountryMask.md

This function retrieves the current country's formatting mask. It's crucial to use this instead of the raw `country.format` value when the mask is dynamic.

```APIDOC
## GET Active Formatting Mask

### Description
Retrieves the formatting mask for the currently selected country based on the provided phone number and country object. This is essential for dynamic formatting masks.

### Method
Utility Function (Not an HTTP method)

### Endpoint
N/A

### Parameters
#### Function Parameters
- **phone** (string) - Required - The phone number in E.164 format.
- **country** (object) - Required - The parsed country object.
- **prefix** (string) - Optional - The phone number prefix (e.g., '+'). Must match the `PhoneInput` prefix if provided.
- **defaultMask** (string) - Optional - The default mask to use if no dynamic mask is found. Must match the `PhoneInput` defaultMask if provided.
- **disableFormatting** (boolean) - Optional - Whether to disable formatting. Must match the `PhoneInput` disableFormatting if provided.

### Request Example
```javascript
const mask = getActiveFormattingMask({
  phone: '+1234567890',
  country: parsedCountryObject,
  prefix: '+',
  defaultMask: '............',
  disableFormatting: false,
});
```

### Response
#### Success Response (string)
- **mask** (string) - The formatting mask for the active country.
```

--------------------------------

### CSS Customization

Source: https://context7.com/ybrusentsov/react-international-phone/llms.txt

Details how to style the PhoneInput component using CSS variables and custom class names for extensive UI customization.

```APIDOC
## CSS Customization

### Description
Styling the phone input using CSS variables and custom class names.

### Usage Example
```tsx
import { PhoneInput } from 'react-international-phone';
import 'react-international-phone/style.css';

function StyledPhoneInput() {
  return (
    <PhoneInput
      defaultCountry="us"
      style={{
        '--react-international-phone-height': '44px',
        '--react-international-phone-background-color': '#f8f9fa',
        '--react-international-phone-text-color': '#333',
        '--react-international-phone-font-size': '16px',
        '--react-international-phone-border-radius': '8px',
        '--react-international-phone-border-color': '#dee2e6',
        '--react-international-phone-disabled-background-color': '#e9ecef',
        '--react-international-phone-disabled-text-color': '#6c757d',
        '--react-international-phone-country-selector-background-color-hover': '#e9ecef',
      } as React.CSSProperties}
      className="custom-phone-input"
      inputClassName="custom-input-field"
      inputStyle={{ fontFamily: 'monospace' }}
      countrySelectorStyleProps={{
        buttonClassName: 'custom-country-button',
        dropdownStyleProps: {
          className: 'custom-dropdown',
          listItemClassName: 'custom-dropdown-item',
        },
      }}
    />
  );
}
```

### CSS Variables for Styling
- `--react-international-phone-height`
- `--react-international-phone-background-color`
- `--react-international-phone-text-color`
- `--react-international-phone-font-size`
- `--react-international-phone-border-radius`
- `--react-international-phone-border-color`
- `--react-international-phone-disabled-background-color`
- `--react-international-phone-disabled-text-color`
- `--react-international-phone-country-selector-background-color-hover`

### Class Names for Styling
- `className`: Applied to the main container of the PhoneInput.
- `inputClassName`: Applied to the input field itself.
- `countrySelectorStyleProps.buttonClassName`: Applied to the country selector button.
- `countrySelectorStyleProps.dropdownStyleProps.className`: Applied to the country dropdown container.
- `countrySelectorStyleProps.dropdownStyleProps.listItemClassName`: Applied to each list item in the country dropdown.
```

--------------------------------

### Forwarding Refs to PhoneInput Component (JavaScript)

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/01-PhoneInput.md

Illustrates how to forward a ref to the PhoneInput component in a JavaScript environment. It shows the basic usage of useRef and attaching it to the PhoneInput element.

```tsx
import { useRef } from 'react';
import PhoneInput from 'react-international-phone';

const PhoneWithRef = () => {
  const ref = useRef(null);
  return (
    <PhoneInput ref={ref} />;
  )
}
```

--------------------------------

### Basic Usage of PhoneInput Component

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/01-getting-started.md

Demonstrates how to use the PhoneInput component in a React application. It includes state management for the phone number and importing the necessary default styles. Ensure you import 'react-international-phone/style.css' for proper styling.

```tsx
import { useState } from 'react';
import { PhoneInput } from 'react-international-phone';
import 'react-international-phone/style.css';

const App = () => {
  const [phone, setPhone] = useState('');

  return (
    <div>
      <PhoneInput
        defaultCountry="ua"
        value={phone}
        onChange={(phone) => setPhone(phone)}
      />
    </div>
  );
};

```

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

--------------------------------

### Import FlagImage Component

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/03-Subcomponents-API/04-FlagImage.md

Demonstrates how to import the FlagImage component from the 'react-international-phone' library. This is the first step before using the component in your application.

```tsx
import { FlagImage } from 'react-international-phone';
```

--------------------------------

### Get Active Formatting Mask with react-international-phone

Source: https://context7.com/ybrusentsov/react-international-phone/llms.txt

Demonstrates how to use the getActiveFormattingMask function to retrieve the dynamic formatting mask for a given phone number and country. This is useful for providing real-time input feedback to the user. It handles different country-specific formats and requires the current phone value, country object, and prefix as input.

```tsx
import { useState } from 'react';
import { PhoneInput, getActiveFormattingMask } from 'react-international-phone';

function PhoneWithMaskInfo() {
  const [phone, setPhone] = useState('');
  const [mask, setMask] = useState('');

  return (
    <div>
      <PhoneInput
        value={phone}
        onChange={(phone, { country }) => {
          setPhone(phone);

          const activeMask = getActiveFormattingMask({
            phone,              // E.164 format phone
            country,            // ParsedCountry object
            prefix: '+',
            defaultMask: '............',
            disableFormatting: false,
          });

          setMask(activeMask);
          console.log('Active mask:', activeMask);
        }}
      />
      <p>Current formatting mask: {mask}</p>
    </div>
  );
}
```

--------------------------------

### Pass Configuration Properties to getActiveFormattingMask

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/05-GetActiveCountryMask.md

Shows how to pass configuration properties like `prefix`, `defaultMask`, and `disableFormatting` to the `getActiveFormattingMask` function. These properties should match those provided to the `PhoneInput` component for consistent formatting.

```tsx
getActiveFormattingMask({
  country,
  phone,
  prefix: '+',
  defaultMask: '............',
  disableFormatting: false,
});
```

--------------------------------

### Import PhoneInput Component

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/01-PhoneInput.md

Demonstrates how to import the PhoneInput component from the 'react-international-phone' library. This is the first step to using the component in your React application.

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

--------------------------------

### Accessing PhoneInput with useRef in React

Source: https://context7.com/ybrusentsov/react-international-phone/llms.txt

This snippet shows how to use the `useRef` hook in React to get a reference to the `PhoneInput` component. This allows for imperative control over the input, such as focusing it, programmatically changing the selected country, or retrieving the current phone number state. It requires importing `useRef` from React and `PhoneInput`, `PhoneInputRefType` from the library.

```tsx
import { useRef } from 'react';
import { PhoneInput, PhoneInputRefType } from 'react-international-phone';

function PhoneWithRef() {
  const phoneRef = useRef<PhoneInputRefType>(null);

  const handleFocus = () => {
    phoneRef.current?.focus();
  };

  const handleSetCountry = () => {
    // Change country programmatically
    phoneRef.current?.setCountry('gb', { focusOnInput: true });
  };

  const handleGetState = () => {
    const state = phoneRef.current?.state;
    if (state) {
      console.log('Current phone (E.164):', state.phone);
      console.log('Display value:', state.inputValue);
      console.log('Country:', state.country.name);
    }
  };

  return (
    <div>
      <PhoneInput ref={phoneRef} defaultCountry="us" />

      <button onClick={handleFocus}>Focus Input</button>
      <button onClick={handleSetCountry}>Set to UK</button>
      <button onClick={handleGetState}>Log State</button>
    </div>
  );
}
```

--------------------------------

### PhoneInput Component Properties

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/01-PhoneInput.md

Detailed documentation of the props available for the PhoneInput component.

```APIDOC
## PhoneInput Component

### Description
The PhoneInput component is a React component used for international phone number input. It supports country guessing, masking, and various customization options for the input field and dropdown.

### Properties
- **value** (string) - Optional - Phone value. Default: ""
- **onChange** ((phone: string, meta: { country: ParsedCountry, inputValue: string }) => void) - Optional - Callback that calls on phone change.
- **defaultCountry** (CountryIso2) - Optional - Default country value (iso2). Default: "us"
- **countries** (CountryData[]) - Optional - An array of available countries to select.
- **preferredCountries** (CountryIso2[]) - Optional - An array of countries to display at the top of the dropdown list.
- **hideDropdown** (boolean) - Optional - Hide the dropdown icon. Default: false
- **disabled** (boolean) - Optional - Disable phone input and country selector. Default: false
- **prefix** (string) - Optional - Prefix for phone value. Default: "+"
- **defaultMask** (string) - Optional - Mask applied to countries without a specified mask. Default: "............"
- **charAfterDialCode** (string) - Optional - Char that renders after country dial code. Default: " "
- **historySaveDebounceMS** (number) - Optional - Save value to history if there were not any changes in provided milliseconds. Default: 200
- **disableCountryGuess** (boolean) - Optional - Disable country guess on value change. Default: false
- **disableDialCodePrefill** (boolean) - Optional - Disable dial code prefill on initialization. Default: false
- **forceDialCode** (boolean) - Optional - Always display the dial code. Default: false
- **disableDialCodeAndPrefix** (boolean) - Optional - Display phone value will not include passed dialCode and prefix. Default: false
- **showDisabledDialCodeAndPrefix** (boolean) - Optional - Show prefix and dial code between country selector and phone input. Default: false
- **disableFocusAfterCountrySelect** (boolean) - Optional - Disable auto focus on input field after country select. Default: false
- **disableFormatting** (boolean) - Optional - Disable phone value mask formatting. Default: false
- **allowMaskOverflow** (boolean) - Optional - Allow input to exceed the mask length. Default: false
- **flags** (CustomFlagImage[]) - Optional - Custom flag URLs array.
- **inputProps** (InputHTMLAttributes) - Optional - Default input component props.

### Usage Example
```tsx
<PhoneInput
  defaultCountry="ua"
  value={phone}
  onChange={(phone) => setPhone(phone)}
/>
```
```

--------------------------------

### Implement PhoneInput Component

Source: https://context7.com/ybrusentsov/react-international-phone/llms.txt

Demonstrates the use of the PhoneInput component for a ready-to-use phone input field with automatic formatting and country selection. It handles state management for the phone number and logs the E.164 formatted value on submission.

```tsx
import { useState } from 'react';
import { PhoneInput } from 'react-international-phone';
import 'react-international-phone/style.css';

function PhoneForm() {
  const [phone, setPhone] = useState('');

  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      console.log('Submitted phone (E.164):', phone);
    }}>
      <PhoneInput
        defaultCountry="ua"
        value={phone}
        onChange={(phone, { country, inputValue }) => {
          setPhone(phone);
          console.log('E.164 phone:', phone);
          console.log('Display value:', inputValue);
          console.log('Country:', country.name);
          console.log('Dial code:', country.dialCode);
        }}
        placeholder="Enter phone number"
        forceDialCode={true}
        preferredCountries={['us', 'gb', 'ua']}
        disabled={false}
      />
      <button type="submit">Submit</button>
    </form>
  );
}
```

--------------------------------

### Implementing Custom Flags in PhoneInput

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/04-CustomCountryFlags/index.md

Demonstrates how to pass an array of flag objects containing ISO2 codes and image sources to the PhoneInput component. If a specific country flag is missing, the component automatically falls back to the default twemoji icon.

```tsx
<PhoneInput
  flags={[
    {
      iso2: 'ua',
      src: '/flags/ua.svg',
    },
    {
      iso2: 'fr',
      src: '/flags/fr.svg',
    },
  ]}
/>
```

--------------------------------

### Forwarding Refs to PhoneInput Component (TypeScript)

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/01-PhoneInput.md

Demonstrates how to forward a ref to the PhoneInput component using TypeScript. It shows how to declare the ref with the correct type 'PhoneInputRefType' and attach it to the PhoneInput element.

```tsx
import { useRef } from 'react';
import PhoneInput, { PhoneInputRefType } from 'react-international-phone';

const PhoneWithRef = () => {
  const ref = useRef<PhoneInputRefType>(null);
  return (
    <PhoneInput ref={ref} />;
  )
}
```

--------------------------------

### Integrate usePhoneInput Hook with Material UI

Source: https://context7.com/ybrusentsov/react-international-phone/llms.txt

Shows how to use the headless usePhoneInput hook to build a custom phone input component using Material UI. This approach provides full control over the UI while leveraging the library's formatting and country selection logic.

```tsx
import { usePhoneInput, CountrySelector, FlagImage, defaultCountries, parseCountry } from 'react-international-phone';
import { TextField, InputAdornment, Select, MenuItem } from '@mui/material';

function MuiPhoneInput({ value, onChange }) {
  const {
    inputValue,
    phone,
    country,
    setCountry,
    handlePhoneValueChange,
    inputRef,
  } = usePhoneInput({
    defaultCountry: 'us',
    value,
    countries: defaultCountries,
    forceDialCode: true,
    disableCountryGuess: false,
    onChange: (data) => {
      onChange(data.phone);
    },
  });

  return (
    <TextField
      value={inputValue}
      onChange={handlePhoneValueChange}
      inputRef={inputRef}
      type="tel"
      InputProps={{
        startAdornment: (
          <InputAdornment position="start">
            <Select
              value={country.iso2}
              onChange={(e) => setCountry(e.target.value)}
              renderValue={(value) => <FlagImage iso2={value} />}
            >
              {defaultCountries.map((c) => {
                const parsed = parseCountry(c);
                return (
                  <MenuItem key={parsed.iso2} value={parsed.iso2}>
                    <FlagImage iso2={parsed.iso2} />
                    {parsed.name} +{parsed.dialCode}
                  </MenuItem>
                );
              })}
            </Select>
          </InputAdornment>
        ),
      }}
    />
  );
}
```

--------------------------------

### Import DialCodePreview Component

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/03-Subcomponents-API/03-DialCodePreview.md

Demonstrates how to import the DialCodePreview component from the 'react-international-phone' library. This is the first step before using the component in your application.

```tsx
import { DialCodePreview } from 'react-international-phone';
```

--------------------------------

### usePhoneInput Hook

Source: https://context7.com/ybrusentsov/react-international-phone/llms.txt

A headless hook that provides phone formatting logic for integration with any input component, enabling custom UI implementations with UI libraries like Material UI, Ant Design, or Chakra UI.

```APIDOC
## usePhoneInput Hook

### Description
A headless hook that provides phone formatting logic for integration with any input component, enabling custom UI implementations with UI libraries like Material UI, Ant Design, or Chakra UI.

### Method
N/A (React Hook)

### Endpoint
N/A (React Hook)

### Parameters
#### Hook Arguments
- **defaultCountry** (string) - Optional - Sets the default country.
- **value** (string) - Required - The current phone number value.
- **countries** (array) - Required - An array of country data objects (e.g., `defaultCountries`).
- **forceDialCode** (boolean) - Optional - If true, the dial code will always be displayed.
- **disableCountryGuess** (boolean) - Optional - If true, automatic country guessing is disabled.
- **onChange** (function) - Required - Callback function when the phone number changes. Receives an object with `phone` (E.164 format), `inputValue` (display format), and `country` object.

#### Hook Return Values
- **inputValue** (string) - Formatted display value of the phone number.
- **phone** (string) - E.164 formatted phone number.
- **country** (object) - The currently selected country object.
- **setCountry** (function) - Function to manually set the country.
- **handlePhoneValueChange** (function) - Event handler for the input element's `onChange` event.
- **inputRef** (ref) - Ref to attach to the input element.

### Request Example
```tsx
import { usePhoneInput, CountrySelector, FlagImage, defaultCountries, parseCountry } from 'react-international-phone';
import { TextField, InputAdornment, Select, MenuItem } from '@mui/material';

function MuiPhoneInput({ value, onChange }) {
  const {
    inputValue,
    phone,
    country,
    setCountry,
    handlePhoneValueChange,
    inputRef,
  } = usePhoneInput({
    defaultCountry: 'us',
    value,
    countries: defaultCountries,
    forceDialCode: true,
    disableCountryGuess: false,
    onChange: (data) => {
      onChange(data.phone);
    },
  });

  return (
    <TextField
      value={inputValue}
      onChange={handlePhoneValueChange}
      inputRef={inputRef}
      type="tel"
      InputProps={{
        startAdornment: (
          <InputAdornment position="start">
            <Select
              value={country.iso2}
              onChange={(e) => setCountry(e.target.value)}
              renderValue={(value) => <FlagImage iso2={value} />}
            >
              {defaultCountries.map((c) => {
                const parsed = parseCountry(c);
                return (
                  <MenuItem key={parsed.iso2} value={parsed.iso2}>
                    <FlagImage iso2={parsed.iso2} />
                    {parsed.name} +{parsed.dialCode}
                  </MenuItem>
                );
              })}
            </Select>
          </InputAdornment>
        ),
      }}
    />
  );
}
```

### Response
#### Success Response (Hook Output)
- The hook returns state and handler functions to manage international phone input within a custom UI.

#### Response Example
(Hook usage within a component, no direct JSON response)
```

--------------------------------

### Implement Basic PhoneInput Component

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/README.md

A basic implementation of the PhoneInput component in a React application. It requires importing the component and its associated CSS styles, and uses React state to manage the phone number value.

```tsx
import { useState } from 'react';
import { PhoneInput } from 'react-international-phone';
import 'react-international-phone/style.css';

const App = () => {
  const [phone, setPhone] = useState('');

  return (
    <div>
      <PhoneInput
        defaultCountry="ua"
        value={phone}
        onChange={(phone) => setPhone(phone)}
      />
    </div>
  );
};
```

--------------------------------

### Implement CountrySelectorDropdown in React

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/03-Subcomponents-API/02-CountrySelectorDropdown.md

Demonstrates how to import and render the CountrySelectorDropdown component. It requires the show, selectedCountry, and onSelect properties to function correctly.

```tsx
import { CountrySelectorDropdown } from 'react-international-phone';

<CountrySelectorDropdown
  show={true}
  selectedCountry="al"
  onSelect={handleSelect}
  onClose={handleClose}
/>
```

--------------------------------

### Custom Country Flags Prop

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/02-Usage/04-CustomCountryFlags/index.md

Demonstrates how to use the `flags` prop to customize country flags in the PhoneInput component.

```APIDOC
## Using the `flags` Prop

### Description

The `flags` prop allows you to specify custom flag images for countries. This is useful for branding or if you have specific flag assets.

### Method

Component Prop

### Endpoint

N/A (Component Prop)

### Parameters

#### Component Props

- **flags** (Array<{ iso2: string, src: string }>) - Required - An array of objects, where each object contains the ISO 3166-1 alpha-2 country code (`iso2`) and the URL to the flag image (`src`).

### Request Example

```jsx
<PhoneInput
  flags={[
    { iso2: 'ua', src: '/flags/ua.svg' },
    { iso2: 'fr', src: '/flags/fr.svg' },
    // ... more countries
  ]}
/>
```

### Response

This prop does not directly return a response. It affects the UI rendering of the flags within the PhoneInput component.

### Notes

- If a flag for a specific country is not provided in the `flags` array, the component will default to rendering a Twemoji country icon.
- You can also customize flag dimensions using CSS variables like `--react-international-phone-flag-width` and `--react-international-phone-flag-height`.
```

--------------------------------

### CSS Customization Variables

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/03-Subcomponents-API/01-CountrySelector.md

A list of CSS variables available to customize the appearance of the country selector component.

```APIDOC
## CSS Variables Reference

### Description
Use these CSS variables to override the default styles of the react-international-phone component.

### Available Variables
| Variable | Default value |
| --- | --- |
| --react-international-phone-country-selector-background-color | --react-international-phone-background-color |
| --react-international-phone-country-selector-background-color-hover | whitesmoke |
| --react-international-phone-disabled-country-selector-background-color | --react-international-phone-disabled-background-color |
| --react-international-phone-country-selector-border-color | gainsboro |
| --react-international-phone-country-selector-arrow-size | 4px |
| --react-international-phone-country-selector-arrow-color | #777 |
| --react-international-phone-disabled-country-selector-arrow-color | #999 |

### Usage Example
```css
:root {
  --react-international-phone-country-selector-border-color: blue;
  --react-international-phone-country-selector-arrow-color: black;
}
```
```

--------------------------------

### Handle country changes with useEffect

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/05-Migrations/04-migrate-to-v2.md

Demonstrates how to replace the removed onCountryChange callback by using the useEffect hook to monitor the country state returned by usePhoneInput.

```javascript
const { country } = usePhoneInput({
  defaultCountry: 'us',
  value,
});

useEffect(() => {
  // move your country change logic here
}, [country]);
```

--------------------------------

### Phone Validation with google-libphonenumber

Source: https://context7.com/ybrusentsov/react-international-phone/llms.txt

Shows how to integrate the google-libphonenumber library for robust phone number validation within the PhoneInput component.

```APIDOC
## Phone Validation with google-libphonenumber

### Description
Integration pattern for validating phone numbers using the google-libphonenumber library.

### Usage Example
```tsx
import { useState } from 'react';
import { PhoneInput } from 'react-international-phone';
import { PhoneNumberUtil } from 'google-libphonenumber';
import 'react-international-phone/style.css';

const phoneUtil = PhoneNumberUtil.getInstance();

const isPhoneValid = (phone: string): boolean => {
  try {
    return phoneUtil.isValidNumber(phoneUtil.parseAndKeepRawInput(phone));
  } catch (error) {
    return false;
  }
};

function ValidatedPhoneForm() {
  const [phone, setPhone] = useState('');
  const isValid = isPhoneValid(phone);

  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      if (isValid) {
        console.log('Valid phone submitted:', phone);
      }
    }}>
      <PhoneInput
        defaultCountry="us"
        value={phone}
        onChange={setPhone}
        inputStyle={{
          borderColor: phone && !isValid ? 'red' : undefined,
        }}
      />

      {phone && !isValid && (
        <span style={{ color: 'red' }}>Please enter a valid phone number</span>
      )}

      <button type="submit" disabled={!isValid}>
        Submit
      </button>
    </form>
  );
}
```

### Helper Function `isPhoneValid`
- **phone** (string) - Required - The phone number string to validate.
- **Returns** (boolean) - True if the phone number is valid, false otherwise.
```

--------------------------------

### PhoneInput Component

Source: https://context7.com/ybrusentsov/react-international-phone/llms.txt

The main component that renders a complete phone input with integrated country selector, dial code display, and automatic formatting based on selected country.

```APIDOC
## PhoneInput Component

### Description
The main component that renders a complete phone input with integrated country selector, dial code display, and automatic formatting based on selected country.

### Method
N/A (React Component)

### Endpoint
N/A (React Component)

### Parameters
#### Props
- **defaultCountry** (string) - Optional - Sets the default country for the input.
- **value** (string) - Required - The current phone number value.
- **onChange** (function) - Required - Callback function when the phone number changes. Receives the E.164 formatted phone number, country object, and display input value.
- **placeholder** (string) - Optional - Placeholder text for the input field.
- **forceDialCode** (boolean) - Optional - If true, the dial code will always be displayed.
- **preferredCountries** (string[]) - Optional - An array of country ISO2 codes to prioritize in the country selector.
- **disabled** (boolean) - Optional - If true, the input will be disabled.

### Request Example
```tsx
import { useState } from 'react';
import { PhoneInput } from 'react-international-phone';
import 'react-international-phone/style.css';

function PhoneForm() {
  const [phone, setPhone] = useState('');

  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      console.log('Submitted phone (E.164):', phone);
    }}>
      <PhoneInput
        defaultCountry="ua"
        value={phone}
        onChange={(phone, { country, inputValue }) => {
          setPhone(phone);
          console.log('E.164 phone:', phone);
          console.log('Display value:', inputValue);
          console.log('Country:', country.name);
          console.log('Dial code:', country.dialCode);
        }}
        placeholder="Enter phone number"
        forceDialCode={true}
        preferredCountries={['us', 'gb', 'ua']}
        disabled={false}
      />
      <button type="submit">Submit</button>
    </form>
  );
}
```

### Response
#### Success Response (Component Render)
- The `PhoneInput` component renders an input field with country selection functionality.

#### Response Example
(Component rendering, no direct JSON response)
```

--------------------------------

### Material UI Phone Input Component (TypeScript)

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/04-Advanced-Usage/02-useWithUiLibs.md

This TypeScript code defines the MuiPhone component for Material UI, including type definitions for props. It mirrors the JavaScript version by using the `usePhoneInput` hook for phone number and country management, integrating with Material UI's TextField and Select. This version adds type safety for the component's props, ensuring better maintainability and developer experience. Dependencies include react, react-international-phone, and @mui/material.

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

import {
  BaseTextFieldProps,
  InputAdornment,
  MenuItem,
  Select,
  TextField,
  Typography,
} from '@mui/material';
import React from 'react';
import {
  CountryIso2,
  defaultCountries,
  FlagImage,
  parseCountry,
  usePhoneInput,
} from 'react-international-phone';

export interface MUIPhoneProps extends BaseTextFieldProps {
  value: string;
  onChange: (phone: string) => void;
}

export const MuiPhone: React.FC<MUIPhoneProps> = ({ 
  value,
  onChange,
  ...restProps
}) => {
  const { inputValue, handlePhoneValueChange, inputRef, country, setCountry } = 
    usePhoneInput({
      defaultCountry: 'us',
      value,
      countries: defaultCountries,
      onChange: (data) => {
        onChange(data.phone);
      },
    });

  return (
    <TextField
      variant="outlined"
      label="Phone number"
      color="primary"
      placeholder="Phone number"
      value={inputValue}
      onChange={handlePhoneValueChange}
      type="tel"
      inputRef={inputRef}
      InputProps={{
        startAdornment: (
          <InputAdornment
            position="start"
            style={{ marginRight: '2px', marginLeft: '-8px' }}
          >
            <Select
              MenuProps={{
                style: {
                  height: '300px',
                  width: '360px',
                  top: '10px',
                  left: '-34px',
                },
                transformOrigin: {
                  vertical: 'top',

```

--------------------------------

### CountrySelector Component API

Source: https://github.com/ybrusentsov/react-international-phone/blob/master/packages/docs/docs/03-Subcomponents-API/01-CountrySelector.md

API documentation for the CountrySelector component, including properties for selection, state, and custom rendering.

```APIDOC
## CountrySelector Component

### Description
The CountrySelector component is a button-based UI element used to select a country from a list. It supports callbacks for selection, disabled states, and custom rendering.

### Properties
- **selectedCountry** (CountryIso2) - Optional - The currently selected country (iso2 code).
- **onSelect** ((country: ParsedCountry) => void) - Optional - Callback function triggered when a country is selected.
- **disabled** (boolean) - Optional - If true, the selector is disabled.
- **hideDropdown** (boolean) - Optional - If true, hides the dropdown icon and disables click interaction.
- **renderButtonWrapper** ((props: { children: React.ReactNode; rootProps: React.ButtonHTMLAttributes<HTMLButtonElement> }) => React.ReactNode) - Optional - Custom render function for the button wrapper.

### Style Properties
- **style** (CSSProperties) - Custom styles for the container.
- **className** (string) - Custom class for the container.
- **buttonStyle** (CSSProperties) - Custom styles for the button.
- **buttonClassName** (string) - Custom class for the button.
- **flagStyle** (dropdownStyleProps) - Custom styles for the flag icon.
- **dropdownArrowStyle** (dropdownStyleProps) - Custom styles for the dropdown arrow.

### Usage Example
```tsx
<CountrySelector
  selectedCountry="ua"
  onSelect={({ iso2 }) => console.log(iso2)}
/>
```
```
Tokens:
Raw