SearchField

This is a text input for a search query. The Escape key and a clear button empty the text, and the Enter key submits the query.

Value: ""

Anatomy

SearchField.Root holds the text and gives the state to each part. Label names the input. Input is the native search input. Clear is the button that empties the text.

<script>
	import { SearchField } from '@human-kit/ui';
</script>

<SearchField.Root>
	<SearchField.Label />
	<SearchField.Input />
	<SearchField.Clear />
</SearchField.Root>

Submit and clear

onSubmit receives the text when the user presses Enter. onClear tells you when the Escape key or the clear button empties the text. Inside a form, Enter also submits the form, and name on Root gives the text a name in the form data.

Usage guidelines

  • Give the input an accessible name. Use SearchField.Label, or put aria-label or aria-labelledby on SearchField.Input.
  • Use bind:value for the state in the two directions. The value is always a string.
  • Use the data-empty attribute to hide the clear button while the text is empty. Use visibility: hidden and not display: none, thus the layout does not move.
  • Some browsers show their own clear button in a search input. Hide it with the ::-webkit-search-cancel-button pseudo-element if you show SearchField.Clear.

Accessibility

  • SearchField.Input makes an <input type="search">, which has the searchbox role. It also sets enterkeyhint="search" for the virtual keyboard.
  • The Escape key empties the text and stops the key. When the text is already empty, the key goes on, thus a dialog or a popover around the field can close.
  • A key in an IME composition belongs to the composition. Thus Escape and Enter do not clear or submit while the user composes text.
  • The clear button is not in the tab order, because the Escape key does the same operation. A screen reader can still find it, and aria-controls points it at the input.
  • A press on the clear button keeps the focus in the input. On a phone, the virtual keyboard stays open.
  • The name of the clear button is "Clear search", in the language of the LocaleProvider. Put an aria-label on SearchField.Clear to change it.

API reference

Root

The container of the search field. It holds the search text and the state, and it gives the context to all of the parts.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description
data-disabled Present when the field is disabled.
data-empty Present when the search text is empty.
data-focus-visible Present when the input shows a keyboard focus ring.
data-focus-within Present when the focus is in the field.
data-invalid Present when the value is invalid.
data-readonly Present when the field is read-only.
data-required Present when the field is required.
data-search-field-root Always present on the root element.

Label

A native label for the input. A click on it moves the focus to the input.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description
data-disabled Present when the field is disabled.
data-search-field-label Always present on the label element.

Input

The native search input. It holds the text, and it handles the `Escape` key and the `Enter` key.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description
data-disabled Present when the field is disabled.
data-empty Present when the search text is empty.
data-focus-visible Present when the focus came from the keyboard.
data-focused Present when the input has the focus.
data-hovered Present when the pointer is on the input.
data-invalid Present when the value is invalid.
data-readonly Present when the field is read-only.
data-required Present when the field is required.
data-search-field-input Always present on the input element.

Clear

The button that empties the search text. It is not in the tab order, and a press on it keeps the focus in the input. It is disabled while the text is empty.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description
data-empty Present when the search text is empty.
data-readonly Present when the field is read-only.
data-search-field-clear Always present on the clear button.