# PhoneInput

A phone number input with a searchable country picker. Formats the national number as the user types and reports the value in E.164, such as `+14155550123`. Typing a number that starts with `+` picks the country from it.

## Use for

- a phone number field
- a phone number with a country code picker

## Practices

- Do: Read and write `value` as E.164. The input formats it for display.
- Do: Pass `country` as well as `value` when calling codes are ambiguous, such as `+1`, and the country is known.
- Do: Pass `name` in a plain `<form>`. A hidden input submits the E.164 value.
- Do: Pass localized strings for the country labels, placeholder and empty message.

## API reference

### PhoneInput

An `InputGroup` with the country trigger, the calling code prefix and the number input. The ref and `Field` wiring go to the number input.

Slot: `cl-phone-input`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The E.164 value, when controlled. |
| `defaultValue` | `string` | `''` | The E.164 value on mount, when uncontrolled. |
| `onValueChange` | `(value: string) => void` |  | Called with the E.164 value when the number or country changes. |
| `country` | `CountryIso` |  | The selected country, when controlled. |
| `defaultCountry` | `CountryIso` | `'us'` | The country when neither `country` nor the value picks one. |
| `onCountryChange` | `(country: CountryIso) => void` |  | Called with the new country. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | `sm`, `md` or `lg`. |
| `countryTriggerLabel` | `string` |  | The country trigger name, with `{country}` filled in. |
| `countryPopupLabel` | `string` |  | The country popup name. |
| `countrySearchLabel` | `string` |  | The country search input name. |
| `countrySearchPlaceholder` | `string` | `'Search'` | The country search placeholder. |
| `noResultsMessage` | `string` | `'No countries found'` | Shown when no country matches the search. |
| `name` | `string` |  | Submits the E.164 value under this name through a hidden input. |
| `autoComplete` | `string` | `'tel-national'` | Passed to the number input. |

## Examples

### A phone field

```tsx
<Field.Root>
  <Field.Label>Phone number</Field.Label>
  <PhoneInput
    value={phone}
    onValueChange={setPhone}
    countryTriggerLabel='Country: {country}'
    countryPopupLabel='Countries'
    countrySearchLabel='Search countries'
  />
</Field.Root>
```

## Related

- [Input](/docs/components/input.md)
- [InputGroup](/docs/components/input-group.md)
- [Field](/docs/components/field.md)
