Search 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 of a container the field draws, from most to least:

• Filled: the shipped default, with the most emphasis; suits the main search of a page, which should stand out among other content.
• Outlined: less emphasis; suits a toolbar or form with several fields, where a lighter box keeps the layout calm.
• Text: no container and no visible label; suits a search that sits inside a frame your layout already draws.

Built in⁠link

• The search icon sits in front of the input, so a search needs no icon of its own.
• input-event-mode can hold back the input event until typing pauses, release it at a steady rate, or wait as long as the user's typing and your search call for. input-rate-limit-delay sets the interval, 300 milliseconds unless you change it. Without a mode, input fires on every keystroke.
• value is current on every keystroke; only the event waits.
• Pressing Enter in the field submits its form, so a search needs no separate submit wiring.
• inputmode offers the search keyboard on a phone unless your app configuration says otherwise.
• badge-value and badge-dot mark a filtered search without a separate element, in the filled and outlined variants.

Using search fields well⁠link

• Keep every field in a form or toolbar in one style, either filled or outlined.
• Give every search field a label that names what it searches, such as "Search recipes", and put guidance in supporting-text.
• Put a correction in error-text; it replaces the supporting text while the field is in error.
• Slot an icon that acts, such as a clear or voice control, as a button with its own accessible name, and leave icons that only decorate unnamed.

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

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

The field comes in three variants: filled, outlined, and text. Set variant to choose one. Omit it and the field takes the variant from your style configuration, which is filled unless you have changed it.

The text variant draws no container, no visible label, no supporting text and no counter. Its label is only the accessible name, so give it a nearby visible cue.

Labels and hints⁠link

label rests in the input's place and floats above it once the field has focus or a value. It is also the accessible name. placeholder is a hint shown while the field is empty, and never names the field. supporting-text adds guidance below the field.

Icons⁠link

The field draws its own search icon at the start. Content in the leading-icon slot replaces it. has-leading-icon follows the slot automatically; set it yourself only when the field is rendered on the server.

For the end of the field, use the trailing-icon slot or trailing-icon-name. If both are present, the slot wins and a warning is logged. has-trailing-icon is set the same way as its leading twin. An icon that does something belongs in the slot as a button with an accessible name.

Badges⁠link

badge-value puts a short text on the field, such as the number of active filters, and badge-dot shows a dot instead. badge-concealed hides the badge while keeping its value, so clearing it shows the same badge again. The text variant draws no badge.

Forms⁠link

The field takes part in forms. It submits value under name, and pressing Enter submits the owning form. A form reset restores the value attribute. autocomplete passes its token to the input, for example off to turn the browser's suggestions off.

The preview blocks form submission in some browsers, so this demo acts from the button's click. On your own page, the form submits.

Errors and limits⁠link

error puts the field in its error state, and error-text replaces the supporting text while it shows. Validation also sets the state when a form submits or reportValidity() is called, never while the reader types. required, minlength, maxlength and pattern supply the rules, and maxlength adds a character counter. The second field below shows the counter.

Disabled and read-only⁠link

disabled disables the field and takes it out of the Tab order. readonly shows a value the reader can select and copy but not edit. The field has no soft-disabled state.

Density⁠link

density runs from 0 to 4, and each step trims the field's vertical padding. Omit it and the field takes its density from your style configuration, which is standard unless you have changed it. The text variant ignores density.

The filled variant hides its label at density 2 and above; the label stays the accessible name, so add a placeholder for the visible hint.

Input event mode⁠link

input-event-mode decides when the field emits input; the four modes are immediate, debounced, throttled and adaptive. Omit it and the field emits on every keystroke, as a native input does. Only the event waits: value is current on every keystroke, and change is never paced.

• immediate passes the native event through untouched.
• debounced emits one input once typing pauses for input-rate-limit-delay.
• throttled emits at most one input per input-rate-limit-delay while typing continues.
• adaptive waits longer for a slow typist or a slow search, and never less than input-rate-limit-delay. Event pacing explains how it measures both.

input-rate-limit-delay is in milliseconds and defaults to 300. asyncSink is the function that runs your search after the field fires input, in every mode, one call at a time. Because it's a function, only code can set it. sink-duty-cycle caps how much of the search's time the field may take up, from 0.01 to 1, and defaults to 1.

Pick a mode, type a few letters quickly, and watch how far the delivered text trails what you type.

Input mode⁠link

inputmode picks the virtual keyboard a phone offers. Omit it and the field offers the search keyboard, from your app configuration, which is search unless you have changed it. Set it to text when a search takes free text that the search keyboard serves badly.

Text direction⁠link

text-direction sets the reading direction of the text. It suits right-to-left languages that write some content left to right, and auto lets the browser pick from the first strong character.

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's role is searchbox. No WAI-ARIA Authoring Practices pattern governs it, because it behaves like a plain text box.

• The accessible name is the aria-label when set, and otherwise label. placeholder never names the field.
• aria-label is the only ARIA attribute that changes what a screen reader announces. Any other aria-* attribute you set, aria-describedby included, has no effect.
• The description is supporting-text, or error-text while the field is in error, followed by the character counter when maxlength is set.
• The field is announced as invalid in the error state, which error or a reported validation error sets. In the filled and outlined variants, error text is announced when it appears.
• required is announced as required and adds an asterisk to the visible label. Do not write the asterisk yourself.
• Screen readers skip the search icon, so it never names the field. Put an icon that acts, such as a clear button, in the trailing-icon slot as a button with its own accessible name.
• The field has no clear button. If you want one, add it as a button in the trailing-icon slot.
• A badge is visual only. It adds nothing to the field's name or description.
• Wrap a page-wide search in a search landmark, as in WAI-ARIA Authoring Practices: Search landmark, so assistive technology users can jump to it.
• For a single line of text that is not a search, a text field suits the job better.

Keyboard and focus⁠link

Typing, caret movement, and selection follow the platform. Enter pressed during IME composition (input-method text entry) is left to the input method.

• Focus shows as a thicker active indicator in the filled variant, a thicker outline in the outlined variant, and a focus ring in the text variant.
• disabled removes the field from the Tab order, and a disabled <fieldset> around it does the same.
• A read-only field keeps its focus and its text selection.
• Reporting a validation error focuses the field, or the form's first invalid field.

Pointer and touch⁠link

The filled and outlined variants are 56 pixels tall at the default density. At the densest setting, density 4, they are still 36 pixels tall, against the 24 by 24 pixels WCAG 2.5.8 asks for. The field is at least 210 pixels wide; see Density.

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 label's float between its resting and floating positions animates for 150 milliseconds, whatever the reduced-motion setting.
• Set text-direction to RTL or auto for input in a right-to-left language.

Standards⁠link

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

• 2.1.1 Keyboard (A)
• 2.4.7 Focus Visible (AA)
• 2.5.8 Target Size (Minimum) (AA)

Four 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.
• 3.3.1 Error Identification (A): put the message that says what is wrong in error-text.
• 3.3.2 Labels or Instructions (A): set label to say what the field searches.
• 4.1.2 Name, Role, Value (A): give a slotted icon button its own accessible name.