Text 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 field stands out, from most to least:

• Filled: a field that must hold its own among other content, such as a search box on a busy page or a short sign-in form.
• Outlined: a form with many fields, where lighter containers keep the page calm, such as a checkout or a settings page.
• Text: a field set into a sentence or a dense layout, with no container and no visible label, such as an inline rename.

Built in⁠link

• required adds the asterisk to the label, and the form checks the field before it is sent.
• A failed rule shows as the field's own error text, in place of the browser's bubble.
• maxlength shows a character counter below the field, read with the field's description.
• Enter inside a form submits it, as a native input does.
• input-event-mode paces the input event while value stays current on every keystroke.
• prefix-text and suffix-text show a symbol or unit beside the value without entering it.

Using text fields well⁠link

• Pick filled or outlined for a form, and use it on every field.
• Label each field with the name of the value, such as "City", and put guidance on what to enter in supporting-text.
• Show a character counter, with maxlength, whenever the value has a length limit.
• Put a symbol or unit that frames the value, such as "@" or "kg", in a prefix or suffix rather than the label.
• Keep icons that only decorate decorative; make an icon that acts a button with its own accessible name.

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

cw-text-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 sets the field's container. filled has a tinted container and an active indicator along its bottom edge; outlined draws an outline around a transparent container; text has no container, and draws no label, supporting text, or counter. Omit it and the field takes the variant from your style configuration, which is filled unless you have changed it. In the text variant label is only the field's accessible name. Choosing a variant says when to use each.

Label and hints⁠link

label names the value. It rests in the input's place and floats above it once the field has focus or a value. supporting-text sits below the field for guidance on what to enter, and placeholder shows a sample value only while the field is empty. maxlength stops input at the limit and shows a counter; minlength sets the shortest value the form accepts.

Prefix and suffix⁠link

prefix-text and suffix-text show fixed text on either side of the input, such as a symbol or a domain. They frame the value without entering it: value holds only what the user typed.

Icons⁠link

leading-icon-name and trailing-icon-name show a Material Symbols icon at either end of the field. For anything else, such as a button that clears the field, place it in the leading-icon or trailing-icon slot; the slot wins over the name when both are set. An icon is decoration, hidden from screen readers, so a slotted button needs its own aria-label.

Badges⁠link

badge-value shows a count or a short word on the field, badge-dot shows a dot instead, and badge-concealed hides the badge while keeping both, so clearing it brings back the same badge.

Validation⁠link

required, minlength, and pattern set the rules the value must meet. The field checks them when its form is submitted or when reportValidity() runs, never while the user types, and shows the browser's message as its own error text. Set error and error-text yourself for a rule only your server knows, such as a username that is taken. In the preview the submit button runs validation without finishing the submit. required adds the asterisk to the label itself, so leave it out of the label and the supporting text.

Forms⁠link

The field submits value under name with its form, and a form reset restores the value it started with. Enter submits the form, after firing change for the edit. autocomplete tells the browser what the value is, such as address-level2 for a city, so it can offer a saved one.

Disabled and read-only⁠link

disabled grays the field out and removes it from the Tab order, and a disabled <fieldset> disables every field inside it. readonly keeps the value fixed while the field stays focusable, so the user can still select and copy it.

Density⁠link

density takes one of five levels, from 0, the standard height, to 4, the most compact. Omit it and the field takes the density from your style configuration, which is level 0 unless you have changed it. From level 2, the filled variant hides its label to save height, and the label remains the accessible name; the outlined variant keeps its label at every level. The text variant ignores density.

Keyboard type⁠link

inputmode picks the on-screen keyboard a phone or tablet offers, such as digits for a verification code. It changes only the keyboard, never what the field accepts. Omit it and the field takes the text keyboard from your app configuration. For an email address, a number, or a phone number, the Email field, Number field, and Phone number field set their own keyboard and check the value too.

Text direction⁠link

text-direction sets the direction of the typed text on its own, apart from the page's. Use LTR for a value written left to right on a right-to-left page, such as an order number, or auto to follow the text the user types.

Input pacing⁠link

input-event-mode decides when the field fires input. immediate, the default, passes every keystroke through. debounced fires once typing pauses for input-rate-limit-delay milliseconds, 300 unless you set it. 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. The Search field paces its input the same way. Type a few words below: the line under the field changes only when input fires.

Set asyncSink to an async function, such as the one that fetches results, and the field calls it after each input it fires, in every mode. sink-duty-cycle caps the share of the function's time the field may use. At 0.25 it leaves the function idle three quarters of the time. Event pacing compares the modes across every component that paces an event.

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

A text field follows a native text input's own semantics rather than a pattern from the WAI-ARIA Authoring Practices.

• The accessible name is label, or the field's aria-label when one is set. placeholder never names the field.
• Any aria-* attribute on the field other than aria-label, aria-describedby included, has no effect.
• The input's description is the field's own text: supporting-text, or error-text while in error, then the counter as "12 / 40" when maxlength is set.
• A screen reader announces the field as invalid in the error state, set by error or by a validation error. 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.
• prefix-text, suffix-text, and the icons stay out of the name and the description. A control placed in an icon slot names itself; see Icons.
• The badge stays out of the field's name and description too, and a dot or a concealed badge is hidden entirely. Put anything the user must know in supporting-text.

Keyboard and focus⁠link

These are a native input's own behavior. Enter submits the owning form, except while an input method is still composing.

• 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 input.
• disabled, or a disabled <fieldset> around the field, takes the input out of the Tab order.
• readonly keeps the field in the Tab order, so its value can still be selected and copied.

Pointer and touch⁠link

• In the filled and outlined variants, a click anywhere on the container focuses the input. The container is at least 210 pixels wide and taller than 24 pixels at every density, above the 24 by 24 pixels of WCAG 2.5.8.
• In the text variant the input itself is the target, one line of text tall, with no container around it.

Display settings⁠link

• Forced colors: a disabled field's label, text, supporting text, and indicator take GrayText, the outlined variant's outline is redrawn as a real border, and the text variant's focus ring takes Highlight.
• Reduced motion: the label's float, a 150-millisecond animation, runs whatever the reader's motion preference.
• Right to left: the typed text follows the page's direction unless text-direction overrides it.

Standards⁠link

With its defaults, the text field meets three WCAG 2.2 success criteria:

• 2.1.1 Keyboard (A)
• 2.1.2 No Keyboard Trap (A)
• 2.4.7 Focus Visible (AA)

Nine more depend on how you use it:

• 1.1.1 Non-text Content (A): give a control in an icon slot its own aria-label.
• 1.3.5 Identify Input Purpose (AA): set autocomplete on a field that asks for the user's own details, such as name or street-address.
• 2.4.6 Headings and Labels (AA): write a label that names the value.
• 2.5.3 Label in Name (A): start an aria-label you set with the visible label's words.
• 2.5.8 Target Size (Minimum) (AA): in the text variant, keep other controls 24 pixels clear of the input.
• 3.3.1 Error Identification (A): set error-text whenever you set error, and describe the error in text beside a text-variant field, which draws none.
• 3.3.2 Labels or Instructions (A): put format rules in supporting-text, and give a text-variant field a visible label, since it draws none.
• 3.3.3 Error Suggestion (AA): write error-text that says how to fix the value, such as "Use lowercase letters and digits."
• 4.1.2 Name, Role, Value (A): give every field a label, or an aria-label where no label shows.