Skip to content
Mosaic
On this page

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

GuidancePractice
DoRead and write value as E.164. The input formats it for display.
DoPass country as well as value when calling codes are ambiguous, such as +1, and the country is known.
DoPass name in a plain <form>. A hidden input submits the E.164 value.
DoPass 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

PropTypeDescription
valuestringThe E.164 value, when controlled.
defaultValuestringThe E.164 value on mount, when uncontrolled.Default: ''
onValueChange(value: string) => voidCalled with the E.164 value when the number or country changes.
countryCountryIsoThe selected country, when controlled.
defaultCountryCountryIsoThe country when neither country nor the value picks one.Default: 'us'
onCountryChange(country: CountryIso) => voidCalled with the new country.
size'sm' | 'md' | 'lg'sm, md or lg.Default: 'md'
countryTriggerLabelstringThe country trigger name, with {country} filled in.
countryPopupLabelstringThe country popup name.
countrySearchLabelstringThe country search input name.
countrySearchPlaceholderstringThe country search placeholder.Default: 'Search'
noResultsMessagestringShown when no country matches the search.Default: 'No countries found'
namestringSubmits the E.164 value under this name through a hidden input.
autoCompletestringPassed to the number input.Default: 'tel-national'

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>