Search
SearchBar puts a search box in the page body, next to the prose.
Every doc site already has a search trigger in the top bar, on ⌘K / Ctrl K.
<SearchBar /> puts a second entry point in the page itself — a full-width
box in the flow of your content.
Use it where the header control is easy to miss: a landing page, a section index, the top of a long reference. It is not worth putting on every page.
What it opens
The same search modal the header trigger opens. There is one search index, one
result list and one keyboard model on a page, no matter how many entry points
you add — so typo tolerance, recent pages, arrow-key navigation and the
"Ask the assistant instead" row all behave exactly as they do from ⌘K.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
placeholder | string | "Search the documentation…" (on doc engine v1, your site's search.placeholder if set) | The text shown inside the box |
kbd | "true" | "false" | "true" | Whether to show the keyboard-shortcut hint on the right |
size, mode, suggestions | The home search box (doc engine v2) |
hint is the deprecated name of kbd. Doc engine v1 and v2 both read it —
hint="false" hides the shortcut hint — and the build warns until its
deprecation window ends. When both are set,
kbd wins. stx migrate renames it.
Set kbd="false" in a narrow column — inside a <Columns>, or in a card —
where the hint would crowd the label.
Home search box
On a doc engine v2 site, size="lg" draws your preset's
home search box — the large box at the top of a docs home — instead of the
in-page bar. Inside a <Hero title> the box is
always the home one, so size isn't needed there.
| Prop | Type | Default | Description |
|---|---|---|---|
size | "lg" | — | Draws the home search box |
mode | "search" | "ask" | "both" | "search" | search opens search; ask sends the question to the AI assistant; both shows the Search / Ask switch |
suggestions | list | "popular" | None | Chips under the box. {["API keys", "Deploy"]} (or "API keys, Deploy") — each searches for itself, up to 6 (Paper and Atlas show 3). "popular" shows your most read pages as links, up to 4 |
ask and both need the assistant. When it's off for the site, the box
searches and the build log says so. placeholder works here too; its default is
"Ask a question about your site" when the box asks, "Search your site"
otherwise. An unknown mode searches, with a build warning.
size, mode and suggestions are doc engine v2 only — a v1 site draws the
in-page bar and ignores them.
Typing in the home search box
The home search box is a real input: readers type straight into it, without a modal opening first.
mode="both") — Search | Ask is a radio group: click
it or use the arrow keys. The placeholder follows it, and each reader's last
choice is remembered for your site.mode="ask",
and the home boxes of Paper, Plain, Grid, Margin and Console) sends the
question to the assistant; one that searches (Atlas's) opens the full search.Results follow the reader's audience, so gated pages only show to readers who can open them. With the assistant off, the box only searches: no switch and no Ask row.
With scripts off, Enter submits the query to /?q=…, which opens
search with it filled in — so https://your-site/?q=webhooks is a shareable
search link.
This applies to the box in a <Hero title> and to
<SearchBar size="lg">. Existing sites get it on their next build.
The shortcut hint
The hint reads ⌘ K on macOS and Ctrl K on everything else, chosen in the browser rather than baked into the page.
Placement
The box is as wide as its column, up to a 34rem reading measure, and sits on its own line. Writing it on one line of MDX is enough — you do not need blank lines around it, and it is never folded into a paragraph with the text above it.
A good hero:
Accessibility and behaviour
⌘K does. This holds
on doc engine v2 sites too. The
home search box is an input instead: its
results are a combobox list, announced to screen readers.The site-wide search box in the top bar is there as well, on every page.
<SearchBar /> adds an entry point; it never replaces one.
When search is off
With search: { "enabled": false }
in syntext.json, an in-page <SearchBar /> renders nothing, on doc engine v1
and v2. Home search boxes ask the assistant instead — no Search / Ask
switch — when it's on, and are left out when it's off or when the box is
mode="search".