Search

The accessible name ("Search products", "Search this site"). Visually hidden by default — the glyph and placeholder are the visible cue.

Accessibility: label/for on the input, visually hidden unless `showLabel`.

Show the label above the field, as in a search page rather than a header.

Field name; the query key when the form submits to a URL.

Controlled query. When set, it is the query everything reads: submit, a chosen suggestion, the clear button and the Form value all use this prop, never stale typed text; clearing reports onChange("") and the field empties when the caller passes the new value.

Initial query.

Example query, not a label ("Try "invoices from March"").

URL to submit to with GET (web and Lit); when omitted, `onSubmit` handles it and nothing navigates. The URL carries the same trimmed query `onSubmit` receives (the field value is trimmed before the native submit): the visible input carries no `name`; a hidden input named `name` is set to the trimmed query (the controlled value or chosen label, never stale DOM text) in the submit handler. Ignored, with a development warning, when Search sits inside a Form component: the enclosing Form owns submission.

Suggestions for the current query, shown in a Listbox under the field; choosing one fills the query with the suggestion's `label` — what the user just read — and submits. Provide them from `onChange` (debounced by the caller). Setting the prop at all is what turns the field into a combobox, including an explicitly empty array after a fetch that found nothing, which shows `copy.noSuggestions`; leaving it undefined keeps a plain search field. With suggestions the field becomes a Combobox: same keys, `aria-activedescendant` on web (Lit uses a live span instead; see platforms.lit). `aria-controls` and `aria-activedescendant` are set only while the list is open, so neither ever points at an element that is not in the document. The composed Listbox gets `label` = Search's `label`, `embedded`, `value: ""` (no persistent selection after a choice), the suggestions as options and, while empty, `emptyMessage` = `copy.noSuggestions` (or `copy.loading` while `loading`); Listbox's own `loading` prop is never used. Wiring props the combobox pattern needs are passed too and are not part of that list: an `id` for aria-controls and option ids, `selectionFollowsFocus: false` so a highlight never selects, `onChange`/`onActiveChange`, and a key that remounts it to clear the highlight; `labelledBy` is not used. The list opens on typing (while `suggestions` is set) and on ArrowDown — never on focus alone, and a `suggestions` array arriving while the field is focused but untouched does not open it. It closes on Escape, on Tab (explicitly, even though Tab moves focus to the clear or submit Button, which is inside Search), on blur to an element outside Search (a blur with no new focus target, such as a window switch, does not close it), on a pointer press outside Search — the same scope as the blur rule, so a press on a shown label or on the submit Button does not close it — on a chosen suggestion, on clear, and on every submit attempt, including one an empty query refuses to send. ArrowDown on the last suggestion stays there (no wrap), as ArrowUp never wraps. The popup is at least as wide as the field (a `min-inline-size` from the field's measured width, as Combobox) and a long suggestion label may widen it.

Suggestions are being fetched; announced through `copy.loading` whenever `suggestions` is set and this is true, list open or not — a fetch the user triggered is worth hearing about. The count and `copy.noSuggestions` announce only while the list is open.

Give the field the `search` landmark. Turn off when the Search sits inside another search landmark (a filter within a results page). It is `role="search"` on Search's own form element, not a composed Landmark wrapping it: the landmark is one attribute on an element this component already renders, and a wrapper would add a second element and take the root's testability hook. With a single search landmark on the page it needs no name of its own beyond the field's label.

lg for a search page's hero field.

Not editable, still readable and focusable: the input is read-only with aria-disabled (on native `editable={false}` with accessibilityState disabled, which as Input is not focusable on iOS), both Buttons are disabled (the clear Button still renders when there is text), every key in the keyboard table is inert, suggestions never open and an open list closes, no event fires, the component dims to `disabledOpacity`, and a disabled Search is not registered with (or submitted by) a Form — on Lit ds-form skips it as disabled and it sends setFormValue(null). A Form-level disabled (the Form's own `disabled`, FormContext) unregisters it the same way, rather than registering and reporting itself disabled.

Fired on every keystroke with the query; the caller fetches suggestions here. Also fired whenever Search itself changes the text, so a controlled value can follow: with "" before `onClear` (clear button or Escape), and with the suggestion's `label` before `onSubmit` when one is chosen.

Fired on Enter, the submit button, or choosing a suggestion, with the query.

Fired when the field is emptied — by the clear button, or by the Escape that clears it when no suggestions are open. Either route reports.