Input Search
A search input with an optional clear button. The clear button appears automatically when the field has a value and disappears once cleared.
Keyboard interaction
| Key | Action |
|---|---|
| Tab | Move focus to the input or the clear button (when visible and non-empty). |
| Shift + Tab | Move focus to the previous focusable element. |
| Type | Enter search text directly into the field. |
| Escape | Clear the field value (browser default behaviour for search inputs). |
| Enter | Submit the enclosing form or trigger the search action. |
Screen reader behaviour
The following ARIA attributes are managed internally by the component:
| Property | Value | Note |
|---|---|---|
role="searchbox" | Assigned automatically by the browser | Communicates the search purpose to assistive technology. |
aria-label="Clear search" | On the clear (×) button | Hidden from the accessibility tree (aria-hidden) when the field is empty or read-only. |
aria-required | "true" when required is set | Communicates the required state to assistive technologies. |
aria-invalid | "true" when state="error" | Signals a validation failure. Paired with aria-describedby pointing at the error message. |
aria-describedby | ID of the message or description element | Links the error or description text to the input so screen readers announce it on focus. |
Label association
The label is paired with the inner <input type="search"> via Shadow DOM id association. It is common to visually hide the label on search fields using hideLabel — the label text is still used as the accessible name.
Role semantics
type="search" implies role="searchbox" in most browsers, communicating the search purpose to assistive technology.
Clear button
When showClearButton causes the clear (×) button to be rendered, it has aria-label="Clear search" and is keyboard focusable. It is hidden from the accessibility tree when the field is empty, disabled, or readonly.
Required fields
required adds a visual asterisk and aria-required="true".
Validation state
state="error" sets aria-invalid="true" and links the message via aria-describedby.
Focus management
delegatesFocus: true forwards host focus to the inner input. The clear button focus ring is rendered by getFocusStyle. Reduced-motion styles respect prefers-reduced-motion.
WCAG 2.2 compliance
1.3.1 Info and Relationships — APass
Label, required indicator, and error message are all programmatically associated with the input via ARIA attributes.
1.4.3 Contrast (Minimum) — AAPass
Input text and label foreground colours meet the 4.5:1 minimum contrast ratio against the field background in both themes.
2.1.1 Keyboard — APass
All functionality is operable via keyboard including the clear button.
2.4.7 Focus Visible — AAPass
A visible focus ring is applied on keyboard focus using :focus-visible styles.
3.3.1 Error Identification — APass
When state="error", the error message is linked via aria-describedby so screen readers announce it on focus.
4.1.2 Name, Role, Value — APass
The inner <input type="search"> exposes role="searchbox"; the clear button has an accessible label at all times.
Best practices
- Reduced motion — all CSS transitions inside the shadow DOM respond to
prefers-reduced-motion: reduceand are suppressed automatically. - Hidden labels — it is common to visually hide search field labels using
hideLabelwhen visual context makes the purpose clear, but the label text must still be provided — it becomes the accessible name for screen reader users. - Error messaging — always pair
state="error"with a meaningfulmessageprop. Colour alone is insufficient for users who cannot distinguish red from other colours.