HeaderSearch
The topbar search pill (mock .search) as a combobox: results come from fetcher (debounced, aborted when the term changes) or from the app (results + onQueryChange). No hit is highlighted until the arrows move: the first ArrowDown highlights the first hit, the first ArrowUp the last (wrapping after that). Enter opens the highlighted hit, or the first when none is. Escape closes the list (a second Escape clears the box), a click outside closes it. Enter never opens a hit that belongs to an older term while the newer one is still being searched. "No results" and "search failed" are said in a live region beside the list, never inside the listbox.
import { HeaderSearch } from '@ergasti/bricks';Examples
Search with a fetcher
After minChars characters and a debounceMs pause the component calls your fetcher(term, signal) and lists the answer by group. Arrow keys move through results, Enter opens one, Escape closes. Try "lai".
Code
import { HeaderSearch, type SearchResult } from '@ergasti/bricks';
import { creators } from './sample-data';
const codeOf = (name: string) => `${name.replace(/\s/g, '').slice(0, 4).toUpperCase()}0329`;
function WithFetcher() {
const fetcher = async (term: string): Promise<SearchResult[]> => {
const q = term.toLowerCase();
return [
...creators.filter((c) => c.name.toLowerCase().includes(q)).slice(0, 4).map((c) => ({ id: `c${c.id}`, label: c.name, sub: codeOf(c.name), group: 'creators' })),
...creators.filter((c) => codeOf(c.name).toLowerCase().includes(q)).slice(0, 3).map((c) => ({ id: `k${c.id}`, label: codeOf(c.name), sub: c.name, group: 'coupons' })),
];
};
return <div style={{ maxWidth: 420 }}><HeaderSearch fetcher={fetcher} placeholder="Search creators, coupons…" groupLabels={{ creators: 'Creators', coupons: 'Coupons' }} onSelect={() => {}} /></div>;
}Results you hold yourself
Pass results, failed and onQueryChange when your own hook does the fetching.
Code
import { HeaderSearch } from '@ergasti/bricks';
function Controlled() {
return <div style={{ maxWidth: 420 }}><HeaderSearch results={[{ id: '1', label: 'Laila Saeed', sub: 'LAIL0329' }]} onQueryChange={() => {}} onSelect={() => {}} /></div>;
}Folding on phones
By default (collapsible) the pill folds into a 44px search button under 600px wide, so the phone header keeps its tools on one row; the button opens the box and moves focus into it, and Escape on the empty box or focus leaving it folds it back. collapsible={false} keeps the pill at every width. Narrow the window to see it.
Code
import { HeaderSearch } from '@ergasti/bricks';
import { creators } from './sample-data';
function Collapsible() {
return (
<div style={{ display: 'grid', gap: 12, maxWidth: 420 }}>
<HeaderSearch placeholder="Search creators, coupons…" fetcher={async () => []} onSelect={() => {}} />
<HeaderSearch collapsible={false} placeholder="Always a pill…" fetcher={async () => []} onSelect={() => {}} />
</div>
);
}Props
Prop
Type
Design guidance
How the BRICKS design system uses HeaderSearch. Written in docs/content/components/HeaderSearch.md; the props above are read from the code, which wins where the two disagree.
The top bar's search pill as a combobox: type a term, get grouped results (Creators, Coupons) under it, pick one with the mouse or arrows and Enter; use it in AppHeader's search slot.
It is the mocks' .search pill ("Search creators, coupons…" in the Brand dashboard, "Search brands, creators…" in the PR Portal). Results come from a fetcher (debounced 300ms, aborted when the term changes) or from the app (results + onQueryChange). Under 600px it folds into a 44px search button that opens the box over the header's tools row.
Anatomy
- Pill (
.kit-shell-search,role="search"): 44px, fully round,--card, 1px--line, a 16px search icon and the input; raspberry border and focus ring while focused. - Fold button (
.kit-shell-search-open, phones,collapsible): a 44px circle named like the box. - Input (
role="combobox",type="search"): placeholder in--ink-3. - Results (
.kit-shell-pop--search,role="listbox"): a 320px+ panel (radius 18) under the pill; untitled results first, then one group pergroupLabelskey with an 11px uppercase heading; each option has a label and a mutedsub. - Status: "Nothing matches that." / "Couldn't search right now. Try again." in a visible line and an always-present live region.
Variants
| Props | Behaviour | Use when |
|---|---|---|
fetcher | Uncontrolled: the component debounces, calls, aborts stale calls | Most apps. |
results + onQueryChange (+ failed) | Controlled: the app searches and passes hits | Search through the app's own data layer. |
collapsible (default true) | Folds to a button under 600px | The header on phones. |
collapsible={false} | Pill at every width | A search inside a page. |
groupLabels | Group order and titles ({ en, ar } allowed) | Mixed result types. |
States
| State | How | Look |
|---|---|---|
| Empty | — | Placeholder. |
| Too short | fewer than minChars (2) | No search, no panel. |
| Results | hits | Listbox open; none highlighted until an arrow key. |
| Highlighted | ArrowDown/ArrowUp | --soft row (aria-selected), wraps. |
| No results | [] | "Nothing matches that." |
| Failed | fetcher rejects, or failed | "Couldn't search right now. Try again." |
| Folded / expanded (phone) | button, focus | Expanded box fills the tools row; folds on blur or Escape when empty. |
Types
SearchResult: { id, label, sub?, group? } (id unique across groups).
SearchFetcher (fetcher): (term, signal) => Promise<SearchResult[]>; reject to show the error line.
Usage
const search: SearchFetcher = async (term, signal) => {
const res = await fetch(`/api/search?q=${encodeURIComponent(term)}`, { signal });
if (!res.ok) throw new Error('search failed');
const { creators, coupons } = await res.json();
return [
...creators.map((c) => ({ id: `c${c.id}`, label: c.name, sub: c.code, group: 'creators' })),
...coupons.map((k) => ({ id: `k${k.id}`, label: k.code, sub: k.creatorName, group: 'coupons' })),
];
};
<AppHeader
title="Creators"
search={<HeaderSearch placeholder="Search creators, coupons…" fetcher={search}
groupLabels={{ creators: { en: 'Creators', ar: 'صنّاع المحتوى' }, coupons: { en: 'Coupons', ar: 'الكوبونات' } }}
onSelect={(hit) => navigate(hit.group === 'coupons' ? `/coupons/${hit.id}` : `/creators/${hit.id}`)} />}
/>// Controlled: the app runs the query
const [term, setTerm] = useState('');
const { data, isError } = useSearch(term);
<HeaderSearch placeholder="Search brands, creators…" results={term ? data ?? null : null} failed={isError}
onQueryChange={setTerm} onSelect={open} />Where it appears
- Brand › every screen › top bar ("Search creators, coupons…"). Screens:
Brand*. - PR Portal › every screen › top bar ("Search brands, creators…"). Screens:
Pr*.
Guidelines
Do
- Group results by type and put the most likely group first in
groupLabels. - Keep each result to a label and one muted line (code, handle).
- Throw from the fetcher on HTTP errors so the error line shows.
Don't
- Don't use it to filter the current table; use
ListToolbar/Toolbarsearch. - Don't return more than about 5 per group.
RTL and Arabic
- The icon is on the right; results align right; group headings drop uppercase in Arabic. Labels and subs use
dir="auto". - Arabic copy: "دوّر…", "مفيش نتايج.", "معرفناش ندوّر دلوقتي. جرّب تاني."
Tokens
--shell-search-w, --shell-search-w-narrow, --card, --line, --ink, --ink-3, --rasp, --focus-ring, --soft (highlight), --focus-ring-inset.
Accessibility
- Combobox pattern:
role="combobox",aria-expanded,aria-controls,aria-autocomplete="list",aria-activedescendantfor the highlighted option; optionsrole="option"witharia-selected; groupsrole="group"witharia-label. - Enter picks the highlighted hit (or the first); never a hit from an older term while a newer one is searching.
- Escape closes the list, a second Escape clears; "no results" and "failed" are in a live region outside the listbox.
- The fold button is named like the box, with
aria-expanded.
Found in the source
- Roles in the markup:
search,combobox,status,listbox,option,group. - ARIA attributes set:
aria-label,aria-expanded,aria-controls,aria-autocomplete,aria-activedescendant,aria-hidden,aria-selected. - Keys the code handles: Escape, Enter, ArrowDown, ArrowUp.
- It moves focus in code.
- Its tests cover: “searches after a pause, groups the hits in groupLabels order and opens one with the keyboard”; “Enter before the newer term answers opens nothing from the older results”; “the first ArrowUp highlights the last hit; Enter with nothing highlighted opens the first”; “Escape closes the list, a second Escape clears the box; a click outside closes it”; “reports the term and lists the results the app passes in, grouped and labelled in Arabic”; “by default draws a search button named like the box that opens the box and moves focus into it”.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
AppHeader: its slot.ListToolbar/Toolbar: in-page filtering.TopbarMenu: the other popovers in the tools row.
See also: Icon · useLanguage · LanguageToggle · LogoutButton
Source
src/shell/HeaderSearch.tsx (line 60) on GitHub.