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
| Guidance | Practice |
|---|---|
| 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 | Description |
|---|---|---|
value | string | The E.164 value, when controlled. |
defaultValue | string | The E.164 value on mount, when uncontrolled.Default: '' |
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 | The country when neither country nor the value picks one.Default: 'us' |
onCountryChange | (country: CountryIso) => void | Called with the new country. |
size | 'sm' | 'md' | 'lg' | sm, md or lg.Default: 'md' |
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 | The country search placeholder.Default: 'Search' |
noResultsMessage | string | Shown when no country matches the search.Default: 'No countries found' |
name | string | Submits the E.164 value under this name through a hidden input. |
autoComplete | string | Passed to the number input.Default: 'tel-national' |
Examples
A phone field
<Field.Root>
<Field.Label>Phone number</Field.Label>
<PhoneInput
value={phone}
onValueChange={setPhone}
countryTriggerLabel='Country: {country}'
countryPopupLabel='Countries'
countrySearchLabel='Search countries'
/>
</Field.Root>