Email 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, from most emphasis to least:

• Filled: the most emphasis, for a field that must hold its own among other content, such as the one email field on a sign-in page.
• Outlined: less emphasis, for a form with many fields, such as an invitation list or a checkout.
• Text: no container and no visible label, for a field whose surroundings already say what it is, such as a recipient line.

Built in⁠link

• The browser's email check runs when the form validates, so a value without an @ and a domain is reported as an error.
• multiple accepts several comma-separated addresses, and the same check covers each one.
• inputmode offers the email keyboard on a phone without any setting from you.
• error-text replaces supporting-text while an error shows, and the filled and outlined variants announce it when it appears.
• required adds the asterisk to the label, so the label needs no * of its own.
• Enter submits the owning form, after committing an edited value.
• input-event-mode paces the input event, from every keystroke to an adaptive wait for your server (Input pacing).

Using email fields well⁠link

• Keep one variant within a form: all filled or all outlined.
• Make the label a name such as "Work email", and put guidance in supporting-text.
• Keep the name in label and use placeholder only for an example address.
• Write error text that says how to fix the address, since it replaces the supporting text while it shows.
• Put an icon that does something in the icon slot as a button; an icon with no action is decoration.

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 email fields only, set the token on the element in your own CSS:

cw-email-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

Omit variant and the field takes the variant from your style configuration, which is filled unless you have changed it. The text variant has no container, no visible label, no supporting text, and no counter, so its label is only the accessible name.

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 an example address while the field is empty. supporting-text sits below the field and is read as part of its description.

Several addresses⁠link

multiple lets one field hold a comma-separated list. The browser's email check then covers each address, so the field reports an error when any one of them is malformed. The button in the demo shows the error state the page sets with error.

Icons⁠link

leading-icon-name and trailing-icon-name name a Material Symbols icon. The leading-icon and trailing-icon slots do the same job with your own content, and a slot wins over a name, with a warning logged. An icon alone never names the field, so an icon that does something belongs in a button.

Badges⁠link

badge-value puts text on a badge, badge-dot shows a dot with no text, and badge-concealed hides the badge while keeping its settings.

Errors⁠link

error puts the field in its error state, and error-text replaces the supporting text while it shows. An empty error-text leaves the supporting text in place. A form's own validation reaches the same state when it reports validity.

Forms⁠link

name is the name the field's value is submitted under. required blocks a submit while the field is empty and adds an asterisk to the label. minlength, maxlength, and pattern add further limits, and maxlength also shows a character counter. autocomplete with the value email lets the browser fill the address.

Pressing Enter in the field commits an edit and submits the owning form, and with no form it does nothing. The preview below blocks real submits, so its button reports the click instead.

Disabled and read only⁠link

disabled turns the field off, and a disabled fieldset around it does the same. readonly keeps the value fixed while the user can still focus the field and select its text.

Density⁠link

density takes five values, from 0 for standard height to 4 for the tightest. Omit it and the field takes the density from your style configuration, which is standard unless you have changed it. The filled variant hides its label at density 2 and above, and the label stays as the accessible name. 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 the keyboard from your app configuration, which is email unless you have changed it. A phone shows the keyboard and the preview does not, so this demo shows the attributes only.

Text direction⁠link

text-direction sets which way the text runs as it is typed. Leave it unset to follow the page, or set LTR to keep an address left to right inside right-to-left text.

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 email input, and no WAI-ARIA Authoring Practices pattern applies.

• The accessible name is the field's aria-label when set, otherwise label.
• 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 an error shows, followed by the character counter when maxlength is set.
• A screen reader announces the field as invalid in the error state, whether error sets it or validation reports it. In the filled and outlined variants the error text is announced when it appears.
• required makes a screen reader announce the field as required and adds an asterisk to the visible label.
• placeholder is a hint and never the name. The text variant shows no label, so give it a label for its accessible name.
• Leading and trailing icons are hidden from assistive technology and never name the field. Put an icon that does something in the slot as a button, and give that button its own name.

Keyboard and focus⁠link

Typing and editing keys are the native input's own behavior. During input method composition, Enter is left to the input method.

• 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 field, or one inside a disabled fieldset, is skipped by Tab. A read-only field stays in the Tab order.

Pointer and touch⁠link

• density changes the field's height, so check an icon that acts as a button against WCAG 2.5.8 (24 by 24 CSS pixels) at the density you choose.

Display settings⁠link

• Forced colors: 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.
• Reduced motion: the label's float between resting and floating animates for 150 milliseconds, and nothing in the field checks the preference.
• Right-to-left: the icons and padding follow the page direction. text-direction leaves the layout alone and turns only the typed text.

Standards⁠link

With its defaults, the email 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 an image in an icon slot an alt, or mark a decorative one.
• 1.3.5 Identify Input Purpose (AA): set autocomplete to email where the field asks for the user's own address.
• 2.5.8 Target Size (Minimum) (AA): make an icon button in a slot at least 24 by 24 CSS pixels.
• 3.3.1 Error Identification (A): write error-text that names the problem and how to fix it.
• 3.3.2 Labels or Instructions (A): set label, or aria-label on the field.
• 4.1.2 Name, Role, Value (A): give every field a label, or an aria-label where no label shows.