Skip to main content

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 via for/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​

SlotRequiredDescription
labelYesVisible label text. Required for accessibility; may be visually hidden via is_label_hidden.

Props​

PropTypeDefaultDescription
actionstring-URL where the form submits.
methodEnum: get, postgetHTTP method for form submission.
namestringqName attribute for the search input.
idstring-HTML id of the input. Used to associate the label. Auto-generated when omitted.
valuestring-Pre-filled value for the search input.
placeholderstring-Placeholder text shown when the input is empty.
autocompletestring-Value for the input autocomplete attribute.
is_requiredboolean-Renders the required attribute on the input.
is_disabledboolean-Renders the disabled attribute on the input and submit button.
is_label_hiddenboolean-Visually hides the label while keeping it available to assistive technology.
button_labelstringSearchSubmit button label or accessible name when icon-only.
button_iconstring-Optional icon symbol name. When set, the button renders as icon-only.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.fluidLayout-Full-width, no max-width.
.containedLayoutYesConstrained to a max-width.
.horizontalOrientationYesChildren flow along the horizontal axis.
.verticalOrientation-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 exposes role="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-label or 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 contained layout value takes its maximum width
  • icon - optional magnifying glass inside the submit button
  • textfield - supplies the base search input styling
  • button - supplies the submit button styling
  • icon - used for icon-only submit buttons