Help Search
Freev1.0.0Search guides, API docs and changelog with quick answers, previews and a fallback to the team.
Build for your project
Code/install build
Usage
Import it and pass your content. The props that matter most are listed next.
Example
import { HelpSearch, type HelpDoc } from "@/components/ui/notchset/blocks/help-search";
export function Help({ docs }: { docs: HelpDoc[] }) {
return <HelpSearch eyebrow="ACME HELP CENTER" docs={docs} popular={["billing", "sso"]} />;
}Props
docs–{ id, kind, title, meta, excerpt, code?, href }[]kind is "guide", "api" or "changelog"; results group by it.
answers–{ keywords, text, source }[]A quick answer shows when the query contains one of its keywords.
popular / defaultQuery–string[] / stringChips that fill the search, and where it starts.
onOpen–(doc) => voidOpen a result; defaults to following its href.
onAskTeam–(query) => PromiseAdds ASK THE TEAM to the no-results state.
Anatomy
- Titles count three times as much as excerpts when ranking.
- Every word must appear somewhere for a result to show.
- COPY LINK makes the href absolute with origin.
HelpSearchdata-slot="help-search"Search, filters, results and preview.
Source
components/ui/notchset/blocks/help-search.tsx
Loading the code
Build for your project
Code/install build
Installation
Base UI
pnpm dlx shadcn@latest add https://beautiful-ui.dev/r/help-search.jsonRadix
pnpm dlx shadcn@latest add https://beautiful-ui.dev/r/radix-nova/help-search.jsonFree, no account or key. Use the command for your project's primitives: a radix-*, new-york or default style in components.json is Radix, a base-* style is Base UI. With the @beautiful-ui registry added, @beautiful-ui/<name> picks for you.
Install by hand
- 1. Add the packages
pnpm add class-variance-authority@^0.7 - 2. Copy the files to these paths (the source, or save them all as a .zip)
- components/ui/notchset/blocks/help-search.tsx
- lib/beautiful-ui/notchset/instrument.tsx
- lib/beautiful-ui/notchset/root.ts
- lib/beautiful-ui/notchset/button-variants.ts
- 3. No stylesheet needed.
- 4. Install what it builds on first: shadcn's cn helper (lib/utils.ts, from npx shadcn init), Segmented Control, the theme foundation (its tokens and base styles)
Styles didn't apply?
The CLI adds the styles to the CSS file named in components.json (tailwind.css). Check that it points at your global stylesheet, that the project uses Tailwind CSS v4, and that the file is imported in your root layout. Installed by hand: paste styles.css into that file.
For coding agents
Give your coding assistant the Markdown guide instead of screenshots.
Use it for
- The front page of a help centre
- Deflecting tickets with answers people can find themselves
Use something else when
- Searching product data: use Command Palette
- A short FAQ: use FAQ
Mistakes to avoid
- Keep quick answers short and link to the article they come from
- Search on the server for large help centres and pass the results as docs
Agents find it by
- help center, help centre, docs search, knowledge base, support search, search articles, self serve, Notchset
Where agents read it
- Guide for this component: https://beautiful-ui.dev/md/help-search.md
- Every component, for tools without MCP: /llms.txt
- MCP server:
https://beautiful-ui.dev/api/mcp(setup)
Behaviour
Keyboard
- /
- Focus the search from anywhere
- ↑ ↓ / Enter / Esc
- Move, open, clear
- ← →
- Change the filter
Accessibility
- The search is a combobox over a listbox with an active option (aria-activedescendant); groups are labelled
- Group folds are buttons with aria-expanded; ↑ ↓ skip folded groups
- The count, the preview and the status line are announced as they change
Motion
- Results
- Rise in 30ms apart; the selected row's bar scales in
- Quick answer
- Rises in when the intent matches
- Groups
- Unroll in 380ms and fold in 260ms
Responsive
- Under 720px (container width) the preview moves under the results; key hints hide under 560px.
Performance
- Ranking runs in memory on each keystroke; fine for a few hundred documents.
Changelog
v1.0.0 · 2026-10-04
First release
