## Overview [#overview]
The **PhoneInput** component provides an international phone number input with country code selection. Built on `react-phone-number-input`, it includes a searchable country selector with flags and automatic phone number formatting.
## Usage [#usage]
```tsx
import { PhoneInput } from "@tilt-legal/cubitt-components/primitives";
```
```tsx
```
The component automatically formats phone numbers according to the selected country's format. It uses the `react-phone-number-input` library which follows international phone number standards.
***
## Examples [#examples]
### Basic [#basic]
A standard phone input with country selection.
```tsx
import { PhoneInput } from "@tilt-legal/cubitt-components/primitives";
export default function Example() {
return (
);
}
```
### Sizes [#sizes]
Phone input in different sizes.
```tsx
import { PhoneInput, Label } from "@tilt-legal/cubitt-components/primitives";
export default function Example() {
return (
);
}
```
***
## API Reference [#api-reference]
### PhoneInput [#phoneinput]
The root component for international phone number input with country selection.
| Prop | Type | Default | Description |
| ---------------- | -------------------------------------- | ------- | -------------------------------------------------------------- |
| `value` | `string` | — | The phone number value in E.164 format (controlled). |
| `onChange` | `(value: string \| undefined) => void` | — | Callback when the phone number changes. |
| `variant` | `"sm" \| "md" \| "lg"` | `"md"` | Size variant of the input. |
| `placeholder` | `string` | — | Placeholder text for the input. |
| `disabled` | `boolean` | `false` | Whether the input is disabled. |
| `readOnly` | `boolean` | `false` | Whether the input is read-only. |
| `defaultCountry` | `Country` | `"AU"` | Default country code (e.g., `"US"`, `"GB"`, `"AU"`). |
| `countries` | `Country[]` | — | Array of country codes to display. Shows all if not specified. |
| `popupClassName` | `string` | — | Additional CSS classes for the country selection popup. |
| `className` | `string` | — | Additional CSS classes for the input element. |
| `aria-invalid` | `boolean` | — | Indicates validation state, applies error styling when true. |
### Types [#types]
```tsx
import type { PhoneCountry } from "@tilt-legal/cubitt-components/primitives";
// PhoneCountry is an alias for the Country type from react-phone-number-input
// Examples: "US", "GB", "AU", "DE", "FR", "JP", etc.
```
### Notes [#notes]
* The component uses `react-phone-number-input` for phone number validation and formatting
* Country flags are displayed using SVG flag components from `react-phone-number-input/flags`
* The phone number value follows the E.164 format (e.g., `"+14155552671"`)
* The country selector includes a searchable dropdown with all countries
* Invalid inputs are visually indicated with error styling when `aria-invalid` is true