Skip to Content
BBRICKSv0.7.4
ShellHeader and menus

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

  1. 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.
  2. Fold button (.kit-shell-search-open, phones, collapsible): a 44px circle named like the box.
  3. Input (role="combobox", type="search"): placeholder in --ink-3.
  4. Results (.kit-shell-pop--search, role="listbox"): a 320px+ panel (radius 18) under the pill; untitled results first, then one group per groupLabels key with an 11px uppercase heading; each option has a label and a muted sub.
  5. Status: "Nothing matches that." / "Couldn't search right now. Try again." in a visible line and an always-present live region.

Variants

PropsBehaviourUse when
fetcherUncontrolled: the component debounces, calls, aborts stale callsMost apps.
results + onQueryChange (+ failed)Controlled: the app searches and passes hitsSearch through the app's own data layer.
collapsible (default true)Folds to a button under 600pxThe header on phones.
collapsible={false}Pill at every widthA search inside a page.
groupLabelsGroup order and titles ({ en, ar } allowed)Mixed result types.

States

StateHowLook
Empty—Placeholder.
Too shortfewer than minChars (2)No search, no panel.
ResultshitsListbox open; none highlighted until an arrow key.
HighlightedArrowDown/ArrowUp--soft row (aria-selected), wraps.
No results[]"Nothing matches that."
Failedfetcher rejects, or failed"Couldn't search right now. Try again."
Folded / expanded (phone)button, focusExpanded 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 / Toolbar search.
  • 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-activedescendant for the highlighted option; options role="option" with aria-selected; groups role="group" with aria-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.

See also: Icon · useLanguage · LanguageToggle · LogoutButton

Source

src/shell/HeaderSearch.tsx (line 60) on GitHub.

On this page