Search
Site search input composed from the native <search> landmark, a
<form>, a <label>, an <input type="search">, and a submit
<button>. The landmark exposes role="search" automatically. The
default layout places the input and submit button side-by-side and
stacks them once the composite is too narrow to hold both on one row -
measured from the component's own width, so it reacts to the slot it
sits in rather than to the viewport. The .vertical value opts into
an always-stacked layout for sidebars and narrow columns.
Usage
When to use
- Site-wide search in the header, footer, or a dedicated search page
- Narrow sidebar search where the input should always stack above the submit button
- Any context where users enter a free-text query and submit it
When not to use
- Filtering an on-page list without a submission step - use a textfield with client-side filtering instead
- Selecting from a fixed set of options - use a select or autocomplete
Do
- Associate a
<label>with the input viafor/id, visually hidden if necessary - Provide a meaningful placeholder and accessible submit label
- Let the native
<search>element provide the landmark role
Don't
- Add
role="search"manually - the<search>element provides it - Rely on placeholder text alone as the label
- Ship a custom dropdown autocomplete as part of this component - search is an input + submit only
API
Slots
| Slot | Required | Description |
|---|---|---|
label | Yes | Visible label text. Required for accessibility; may be visually hidden via is_label_hidden. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
action | string | - | URL where the form submits. |
method | Enum: get, post | get | HTTP method for form submission. |
name | string | q | Name attribute for the search input. |
id | string | - | HTML id of the input. Used to associate the label. Auto-generated when omitted. |
value | string | - | Pre-filled value for the search input. |
placeholder | string | - | Placeholder text shown when the input is empty. |
autocomplete | string | - | Value for the input autocomplete attribute. |
is_required | boolean | - | Renders the required attribute on the input. |
is_disabled | boolean | - | Renders the disabled attribute on the input and submit button. |
is_label_hidden | boolean | - | Visually hides the label while keeping it available to assistive technology. |
button_label | string | Search | Submit button label or accessible name when icon-only. |
button_icon | string | - | Optional icon symbol name. When set, the button renders as icon-only. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.fluid | Layout | - | Full-width, no max-width. |
.contained | Layout | Yes | Constrained to a max-width. |
.horizontal | Orientation | Yes | Children flow along the horizontal axis. |
.vertical | Orientation | - | Children flow along the vertical axis. |
Examples
Sizes
Sm, default, and lg variants stacked vertically. Input and submit button scale together.
Horizontal
Default inline layout with input and button on one row.
Vertical
Always-stacked layout for sidebar search and narrow columns.
Header with icon
Icon-only submit button with visually hidden label for compact header placement.
Disabled
The disabled state, which mutes the input and its submit button together and drops both out of the tab order.
Accessibility
- WCAG 2.2 AA
- Native
<search>landmark exposesrole="search"automatically <label>must be present; may be visually hidden<input type="search">provides the native clear control- Submit button is keyboard operable and shows a visible focus ring
- Icon-only submit buttons have an accessible name via
aria-labelor a visually hidden span - Form submission follows standard HTML (Enter key submits)
- Logical tab order is preserved in both horizontal and vertical orientations
Dependencies
- textfield - base styling for
<input type="search"> - button - submit button styling
- container - the
containedlayout value takes its maximum width - icon - optional magnifying glass inside the submit button