/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Components Search

Search

SearchBar puts a search box in the page body, next to the prose.

5 min read

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.

mdx
<SearchBar />
Search the documentation…⌘K

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

PropTypeDefaultDescription
placeholderstring"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, suggestionsThe 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.

mdx
<SearchBar placeholder="Search the API reference…" />
<SearchBar kbd="false" />

Set kbd="false" in a narrow column — inside a <Columns>, or in a card — where the hint would crowd the label.

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.

mdx
<SearchBar size="lg" mode="both" suggestions={["API keys", "Webhooks", "Deploy"]} />
PropTypeDefaultDescription
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
suggestionslist | "popular"NoneChips 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.

The home search box is a real input: readers type straight into it, without a modal opening first.

•
Search — up to six results appear under the box as you type, then Ask the assistant about … as the last row when the assistant is on. ↑ ↓ pick a row; Enter opens it, or, with no row picked, opens the full search with the query filled in.
•
Ask — Enter (or the send button) opens the assistant with the question already sent; the answer streams there and the reader carries on the conversation. The box clears.
•
The switch (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.
•
No switch — with the assistant on, results still appear as you type, and Enter does what the box is for: a box that asks (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.
•
⌘K / Ctrl+K focuses the box while it's on screen; otherwise it opens the search modal as usual. Esc closes the results, then clears the box.

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:

mdx
# Gravv documentation
Everything you need to integrate, in one place.
<SearchBar placeholder="Search the documentation…" />
<CardGroup cols={2}>
<Card title="Quickstart" icon="zap" href="/quickstart">Be live in five minutes.</Card>
<Card title="API reference" icon="key" href="/api">Every endpoint, every field.</Card>
</CardGroup>

Accessibility and behaviour

•
Keyboard — the in-page bar is a button. Tab to it, press Enter or Space, and the modal opens with focus in the input, exactly as ⌘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.
•
Touch — 44px tall, past both the WCAG 2.5.8 24px minimum and the 44px Apple and Google ask for.
•
Right-to-left — the icon, label and hint lay out from the reading edge, so an Arabic or Hebrew page mirrors without any extra configuration.
•
Print — not printed. A search box on paper is a box.
•
JavaScript disabled — not rendered. The modal, the index and the shortcut are all JavaScript, so there is nothing behind the control; a box that swallows a click is worse than no box. The prose around it, the navigation sidebar, the section tabs and every link on the page are unaffected.
Note

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".

Was this page helpful? Yes No
Previous
Product
Resources
Company
© 2026 SyntextBuilt with Syntext