Search Field
A search box with a debounced search event, a clear button, a keyboard shortcut hint and recent searches.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
value | string | — | The query. Setting the attribute after the user has typed no longer updates it, like a native input. |
placeholder | string | — | Text shown while the field is empty. |
aria-label | string | null | null | Accessible name of the field. Defaults to the placeholder, then to "Search". |
name | string | — | Form field name: the query is submitted with the form under this name. |
disabled | boolean | false | Disables the field, its shortcut and the recent searches. |
loading | boolean | false | Shows a spinner in place of the search icon while results are being fetched. |
debounce | number | 300 | Milliseconds of typing pause before search fires. 0 fires on every keystroke. |
shortcut | string | — | Keyboard shortcut that focuses the field from anywhere on the page, e.g. mod+k or / (alternatives separated
by commas). Shown as a hint while the field is empty and unfocused. |
recent | string[] | [] | Recent searches, most recent first. As an attribute, separated by semicolons. |
history-key | string | — | When set, the field records committed searches into recent itself and keeps them in localStorage under this key. |
recent-limit | number | 5 | Most recent searches shown, and kept under history-key. |
escape | 'clear' | 'none' | clear | What Escape does once the recent-searches panel is closed: clear empties the field, none keeps the query and
lets the key bubble on to a container that closes on Escape, such as a find bar. The browser's own clearing of a
search input is cancelled either way, so the container sees defaultPrevented. |
recent-label | string | — | Heading of the recent-searches panel. Defaults to "Recent searches" in the nearest lang (English, or a language the app adds). |
Slots
| Name | Description |
|---|---|
search-icon | Replaces the magnifier at the start of the field. |
clear-icon | Replaces the cross of the clear button. |
suffix-icon | Icon or control at the end of the field, after the clear button and the shortcut hint (a filter toggle, for instance). |
recent-icon | Replaces the clock shown before each recent search. |
Events
| Name | Type | Description |
|---|---|---|
clear | Event | Fired when the clear button or Escape emptied the field, before input, change and search. |
input | Event | Re-dispatched from the inner input on every keystroke; also fired when the clear button or a recent search changes the value. |
change | Event | Re-dispatched from the inner input when the value is committed; also fired when the clear button or a recent search changes the value. |
recent-change | CustomEvent<SearchFieldRecentChangeDetail> | Fired when the field changed recent itself: a search recorded under history-key, or the Clear button. Does not bubble. |
search | CustomEvent<SearchFieldSearchDetail> | The query to run: after the debounce while typing, at once on Enter, on a recent search, and with an empty value when cleared. Does not bubble; listen on the element. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-search-field--min-height | pixel | 36px | |
--c2-search-field--padding | padding | 6px 10px | |
--c2-search-field--gap | pixel | 8px | Space between the icons, the text and the hint. |
--c2-search-field--color | color | #18181b | |
--c2-search-field--background | color | #ffffff | |
--c2-search-field--border | border | 1px solid #bcbcc6 | |
--c2-search-field--border-radius | border-radius | 6px | |
--c2-search-field--font-size | font-size | 14px | |
--c2-search-field--font-family | font-family | — | |
--c2-search-field__placeholder--color | color | #71717a | |
--c2-search-field__hover--border | border | 1px solid #a1a1aa | |
--c2-search-field__focus--border | border | 1px solid rgb(2, 101, 220) | |
--c2-search-field__focus--background | color | — | |
--c2-search-field__focus--outline | outline | none | |
--c2-search-field__error--border | border | 1px solid #dc2626 | Shown while an enclosing c2-form-field shows an error. |
--c2-search-field__disabled--opacity | opacity | 0.38 | |
--c2-search-field__icon--size | pixel | 16px | |
--c2-search-field__icon--color | color | #71717a | |
--c2-search-field__clear-icon--color | color | #a1a1aa | |
--c2-search-field__clear-icon__hover--color | color | #18181b | |
--c2-search-field__spinner--color | color | rgb(2, 101, 220) | |
--c2-search-field__shortcut--height | pixel | 20px | |
--c2-search-field__shortcut--padding | padding | 0 6px | |
--c2-search-field__shortcut--color | color | #71717a | |
--c2-search-field__shortcut--background | color | #fafafa | |
--c2-search-field__shortcut--border | border | 1px solid #e4e4e7 | |
--c2-search-field__shortcut--border-radius | border-radius | 4px | |
--c2-search-field__shortcut--font-size | font-size | 12px | |
--c2-search-field__panel--background | color | #ffffff | |
--c2-search-field__panel--border | border | 1px solid #e4e4e7 | |
--c2-search-field__panel--border-radius | border-radius | 8px | |
--c2-search-field__panel--box-shadow | box-shadow | 0 12px 32px rgba(24, 24, 27, 0.14) | |
--c2-search-field__panel--max-height | pixel | 320px | |
--c2-search-field__panel--padding | padding | 4px | |
--c2-search-field__panel--offset | pixel | 6px | Gap between the field and the panel. |
--c2-search-field__header--padding | padding | 6px 8px | |
--c2-search-field__header--color | color | #71717a | |
--c2-search-field__header--font-size | font-size | 12px | |
--c2-search-field__header--font-weight | font-weight | 500 | |
--c2-search-field__header-action--color | color | rgb(2, 101, 220) | |
--c2-search-field__header-action__focus--outline | outline | 2px solid rgba(2, 101, 220, 0.4) | Keyboard focus ring of the Clear button. |
--c2-search-field__option--min-height | pixel | 32px | |
--c2-search-field__option--padding | padding | 6px 8px | |
--c2-search-field__option--gap | pixel | 8px | |
--c2-search-field__option--border-radius | border-radius | 4px | |
--c2-search-field__option--color | color | #18181b | |
--c2-search-field__option__active--background | color | #f4f4f5 | |
--c2-search-field__option-icon--color | color | #71717a | |
--c2-search-field__highlight--font-weight | font-weight | 600 | |
Text and languages
The text the component shows, in English. It shows another language when the app adds one with addTranslations, under search-field, and the nearest lang asks for it; any message not translated stays in English. {0}, {1}… stand for the values a message carries. Languages guide.
| Key | English | Values |
|---|---|---|
search | Search | — |
clearSearch | Clear search | — |
recent | Recent searches | — |
clear | Clear | — |
clearRecent | Clear recent searches | — |