SearchBox
SearchBoxContent discovery Search the built site with a native input and Pagefind-powered results.
Site navigation & servicesSearch the component guides
Try “virtual”, “checkbox” or “variant”, then follow a matching result.
A native search field, real results, and Pagefind configuration. Open the source tab to adapt the composition.
<SearchBox tone="neutral" variant="surfaceAlt" /> All ten semantic tones
All supported values are visible together on the actual component, in an isolated document.
Samples follow this guide’s theme. Service appearance comparisons do not register account, search, or consent services.
All eighteen visual variants
All supported values are visible together on the actual component, in an isolated document.
Samples follow this guide’s theme. Service appearance comparisons do not register account, search, or consent services.
Search states and configuration
The live field above searches the real documentation index. Try a matching term, a term with no matches, then clear it; the results region is separate from the native field. Appearance samples are isolated fields without their own search index.
Empty query Focus the search field to see a search prompt. Enter at least two characters to search the site.
Matching query Try virtual or checkbox. Follow a result to the corresponding documentation page.
No matching pages Try no-match-example-12345. The runtime renders its no-results feedback.
No index A field alone does not create an index. Enable site.pagefind and include the generated Pagefind assets and search runtime.
Use the working field to see actual result links; these labelled cards explain the states without hiding them in a selector.
The default placeholder uses site.siteTitle. Supply a placeholder prop to customize the field for its context.
Feature map
| Feature | Where to explore it |
|---|---|
| A native search field, real results, and Pagefind configuration | Context preview, feature comparisons, and original copyable source examples. |
| Public appearance options | Complete galleries above. Only options supported by this component are shown. |
| Native semantics and integration | Behavior notes and API contracts below explain the component’s roots, slots, and runtime dependencies. |
This component exposes tone and variant, but no variantMode.
Behavior and accessibility
Pagefind indexes the built HTML, so new content appears after a successful indexed build. SearchBox does not fetch application records or replace autocomplete. Keyboard behavior and results are provided by the standard Pagefind search runtime.
Press / outside an editable field to focus the first visible search box. Use the up and down arrow keys to move between results, Enter to open the focused link, and Escape to dismiss the panel. Tab follows the normal link order. Result counts and search errors are announced to screen readers.
API reference
SearchBox contract
Props below are the public template API. RefOrValue accepts a literal or a reactive ref; bind refs with a colon-prefixed attribute. Native attributes and events can be passed through the component root.
tone
RefOrValue<SemanticTone> - Default
inherited
Semantic intent: neutral, accent, secondary, info, success, warning, danger, feature, custom or ghost. The active skin supplies the colors.
variant
RefOrValue<ComponentVariant> - Default
inherited FormInputField surfaceAlt
Visual treatment. Accepts solid, surface, surfaceAlt, spotlight, glass, flat, flatAlt, flatSolid, outlineFill, outline, subtle, subtleBtn, link, sheen, underline, rail, bracket or none.
placeholder
RefOrValue<string> - Default
Search + site title
Custom field placeholder. When omitted, the component uses site.siteTitle, or simply Search when the site has no title.
Composition
No slots. Register defineSearchComponents with FormInputField and Icon. Enable site.pagefind.enabled and serve the generated Pagefind assets alongside the site.
Site configuration
{
"pagefind": {
"enabled": true,
"excludePaths": []
}
}