Phone number field

Choosing a text field⁠link

Seven components share the text field's form. Each suits a different kind of value:

Two jobs belong elsewhere. A choice from a fixed list is a select, and a number picked by feel rather than typed exactly is a slider.

Choosing a variant⁠link

Three variants set how much a phone number field stands out, from most to least:

• Filled: a field that stands out among other content, such as a contact form with few fields.
• Outlined: a quieter field that keeps a form with many fields easy to scan, such as an address book entry.
• Text: a bare value with no container and no visible label, such as a number edited in place inside a table row.

Built in⁠link

• inputmode defaults to the dial pad on a phone.
• pattern is preset to digits only, and takes the format you accept in its place.
• leading-icon-name and trailing-icon-name add an icon without a slot, and badge-value adds a badge without a second element.
• error-text replaces supporting-text while the field is in error, and maxlength adds a character counter.
• name and value submit with the owning form, and a form reset restores the field.
• input-event-mode paces the input event, from every keystroke to an adaptive wait for your server (Input pacing).

Using phone fields well⁠link

• Use one variant throughout a form: all filled or all outlined.
• Write the label as a name, such as "Mobile number", and put the format you expect in supporting-text.
• Show a country code as prefix-text, so people type only the rest of the number.
• Set pattern to accept a plus sign and spaces whenever people may enter international numbers.
• Write error-text that says how to fix the number, such as "Use digits only, with no spaces."
• Mark a required field with required, which adds the asterisk, and never type an asterisk into the label.

Theming fields⁠link

Set one design token and every field of that variant follows it: text fields, text areas, selects, and the email, number, password, search, and telephone fields alike.

• --ct-field-filled-* themes filled fields, --ct-field-outlined-* outlined fields, and --ct-field-text-* fields with no container.
• A token set on the page, or on any element that contains fields, reaches every field of its variant inside it.
• To restyle telephone fields only, set the token on the element in your own CSS:

cw-tel-field {
  --ct-field-outlined-corner-shape: square;
}

The Styling tab lists every token and its default.

These rules follow Material 3 Expressive's guidance for text fields, on material.io.

Variants⁠link

variant takes filled, outlined, or text. Omit it and the field takes the variant from your style configuration, which is filled unless you have changed it. The text variant has no container and no visible label, so label is only its accessible name. Choosing a variant says when to use each.

Labels and hints⁠link

label rests in the input's place and floats above it once the field has focus or a value. placeholder shows a sample value while the field is empty. supporting-text sits below the field, prefix-text and suffix-text sit beside the value without becoming part of it, and autocomplete tells the browser what to offer.

Icons⁠link

leading-icon-name and trailing-icon-name take a Material Symbols name. A leading-icon or trailing-icon slot takes your own content, and it wins when both are set.

Badges⁠link

badge-value sets the badge's text, and badge-dot shows a dot with no text instead. badge-concealed hides the badge and keeps its value, so clearing it shows the same badge again.

Forms⁠link

name is the key and value is the submitted string. Enter submits the owning form, and a form reset restores the value attribute. The preview cannot finish a submit, but the submit button still runs validation, so the field reports its error.

Validation⁠link

pattern defaults to [0-9]*, so a number with spaces, a plus sign, or dashes fails when validation is reported, which happens on a form submit or a call to reportValidity(). Set pattern for the format you accept. required, minlength, and maxlength also apply, and maxlength adds a character counter. In this demo, the first field keeps the default and the second sets its own pattern.

Errors⁠link

error puts the field in its error state, which overrides an error from reportValidity(). error-text replaces the supporting text while error is set; while it is empty, the supporting text keeps showing. Set both when your own code finds the problem.

Disabled and read-only⁠link

disabled grays the field out and removes it from the Tab order, and a disabled <fieldset> has the same effect. readonly shows a value that cannot be edited but can still be copied.

Density⁠link

density takes whole numbers from 0 to 4. Omit it and the field takes its density from your style configuration, which is standard (0) unless you have changed it. The filled variant drops its visible label from density 2, and the text variant ignores density.

Input pacing⁠link

input-event-mode decides when the field fires input. immediate, the default, fires on every keystroke. debounced fires once typing pauses for input-rate-limit-delay, 300 milliseconds unless you set it, and throttled fires at most once per interval while typing continues. adaptive waits for a pause measured from how this user types and how fast asyncSink answers, never shorter than input-rate-limit-delay. Only the event waits: value is current on every keystroke.

asyncSink and sink-duty-cycle work as on the text field. Event pacing compares the modes across every component that paces an event.

Input mode⁠link

inputmode picks the virtual keyboard a phone offers. Omit it and the field takes tel, the dial pad, from your app configuration unless you have changed it. Set numeric to offer a number pad instead. A desktop browser shows no difference.

Text direction⁠link

text-direction forces the reading direction of the typed digits. It suits a right-to-left page where a phone number is still written left to right, and the opposite case.

Each attribute value has its own tokens; a cell shows its token's value, and selecting the cell shows the token's fallback path, with each name and value ready to copy. For example, the filled column's active-indicator-color row is --ct-field-filled-active-indicator-color, which defaults to --ct-sys-color-on-surface-variant.

Variant⁠link

Names and states⁠link

The field behaves as a native telephone input, a text input with no WAI-ARIA Authoring Practices pattern of its own.

• The field's accessible name is its aria-label when set, and otherwise label.
• Where the field hides its label, it stays the accessible name: in the text variant, and in the filled variant from density 2.
• Any aria-* attribute on the field other than aria-label, aria-describedby included, has no effect.
• The input's description is the supporting text, or the error text while the field is in error, followed by the counter as n / max.
• A placeholder is never the field's name. prefix-text and suffix-text are in neither the name nor the description.
• A screen reader announces the field as invalid in the error state, set by error or by an error that validation reported. In the filled and outlined variants, it announces the error text as it appears.
• required makes a screen reader announce the field as required and adds an asterisk to the visible label, so never type one yourself.
• An icon never names the field. An icon that does something belongs in the leading-icon or trailing-icon slot as a button with its own accessible name.

Keyboard and focus⁠link

• Typing, caret movement, and selection are the native input's own behavior. The submit on Enter is the field's: it does nothing without a form, and it leaves Enter to the input method editor during composition.
• Focus thickens the active indicator in the filled variant and the outline in the outlined variant. The text variant draws a focus ring around the text.
• A disabled input leaves the Tab order, whether disabled or a disabled <fieldset> disabled it. There is no soft-disabled state.
• A read-only field stays in the Tab order.
• Validation shows its error when reportValidity() is called or a form submit runs validation, and the field, or the form's first invalid field, takes focus. checkValidity() never shows an error.

Pointer and touch⁠link

• The field's height depends on variant and density. Check the height you choose against the 24 by 24 pixel minimum of WCAG 2.5.8, particularly at the highest densities.

Display settings⁠link

• In forced-colors mode, a disabled field's label, content, supporting text, and indicator take GrayText. The outlined border is redrawn as a real border, and the text variant's focus ring is Highlight.
• The floating label animates for 150 milliseconds and does not check the reduced-motion preference.
• The input text takes its direction from text-direction. Nothing else in the field mirrors on its own.

Standards⁠link

With its defaults, the phone number field meets two WCAG 2.2 success criteria:

• 2.1.1 Keyboard (A)
• 2.4.7 Focus Visible (AA)

Six more depend on how you use it:

• 1.1.1 Non-text Content (A): give a slotted image an alt, or mark a decorative one as decorative.
• 1.3.5 Identify Input Purpose (AA): set autocomplete to a telephone token such as tel so browsers can fill the field.
• 2.5.8 Target Size (Minimum) (AA): check that the field's height at your chosen density is at least 24 pixels.
• 3.3.1 Error Identification (A): write error-text that says what to fix.
• 3.3.2 Labels or Instructions (A): give every field an label or an aria-label.
• 4.1.2 Name, Role, Value (A): give every field a label, or an aria-label where no label shows.