All components (204)

Phone

Fields · PhoneField

What it is and when to use it

The phone with country prefix and number in the same box, but as two controls: a Select for the prefix and a tel field for the number. The value goes in and out in E.164 (+34612345678), which is what is stored; what is typed may contain spaces, hyphens, dots or parentheses, which are removed from the value automatically (in the field they stay as they were typed).

When to use it

Any phone number that will be stored to call or send an SMS.
Controlled, with value and onChange, or uncontrolled, with initialValue (or nothing): then the field keeps what is typed by itself. In both cases, the chosen prefix stays even if the number is empty.
It includes the 244 countries and territories with an ITU international prefix, each with its flag and its name in the active language (Intl.DisplayNames), in alphabetical order. prefixes replaces the list with your own (shown in the order it arrives), initialPrefix says which prefix is selected at the start (+34) and initialCountry the country, which is needed when the prefix is shared: +1 alone is the United States, initialCountry="CA" is Canada.
A stored number splits automatically by its prefix, and if the prefix is shared, by its first digits: +1 809… is the Dominican Republic and +44 1481… Guernsey.
looksLikePhone(value) checks the shape before submitting (E.164, 6 to 15 digits); whether the number exists is for the caller to know, not the form.

When not to

A number that is not a phone (a postal code, a reference): TextField.

Keyboard: Tab reaches the prefix first and then the number. On the prefix, Enter, Space or the arrow keys open the list with the chosen country in view. With the list open, typing the name searches ("Fra" leads to France; the space keeps searching, "United K"), the arrow keys move one at a time, Page Up and Page Down ten at a time, Home and End to the ends, Enter chooses and Escape closes, returning focus. With the mouse, the wheel scrolls the list. When the country changes, the number is kept.

Accessibility: both controls have their own name: "Country code" and the label of the field. The trigger shows the flag and the prefix ("+34"); in the list, each option is named by its country and its prefix ("Spain (+34)"). The flag is decorative. The hint and the error describe the number, and on mobile the phone keypad appears.

Fine-tuning: no variables of its own: it uses those of the field (--amset-field-*), which the prefix inherits, and it is adjusted with the classes amset-phone__group, amset-phone__prefix, amset-phone__separator, amset-phone__number and, in the list, amset-phone__option, amset-phone__country and amset-phone__dial.

What it looks like

Contact phone number

Country code

To notify you when the order ships

Saved as +34612345678

<PhoneField
  label="Contact phone number"
  hint="To notify you when the order ships"
  value={telefono}
  onChange={setTelefono}
/>

Props

Import it with import { PhoneField } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`label`required	`string`	Required: a field without a visible label does not get into the library.
`className`	`string`	—
`disabled`	`boolean`	—
`error`	`string`	—
`hint`	`string`	—
`initialCountry`	`string`	Country chosen at start, by its ISO code (`'CA'`). It wins over `initialPrefix`, and is needed when the prefix is shared: a bare `+1` is the United States.
`initialPrefix`	`string`	Prefix that appears chosen at the start. By default, Spain (`+34`).
`initialValue`	`string`	Uncontrolled: the value it starts with, in E.164. What is typed afterwards is kept by the field.
`name`	`string`	So the phone travels in a native form. What is sent is the number in E.164 (`+34612345678`), not the part shown in the field.
`onChange`	`(e164: string) => void`	—
`placeholder`	`string`	—
`prefixes`	`readonly CountryPrefix[]`	The list of countries. By default, the 244 with an international prefix (`DEFAULT_PREFIXES`), named in the active language and sorted by that name. A list of your own is shown in the order it arrives.
`required`	`boolean`	—
`size`	`"sm" \| "md" \| "lg"`	—
`value`	`string`	Controlled, in E.164: `+34612345678`. With `onChange`, whoever uses it stores the change.
`variant`	`FieldVariant`	—

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: