Search

Overview.

Search is a combobox: an input that owns its own listbox of suggestions. The user types, the parent narrows the list, the component renders it. Picking a row commits the suggestion throughonSelect and closes the menu. The component never decides what counts as a match — that's the parent's job.

When to use Search.

Reach for Searchwhen there's a finite list to narrow against and the outcome is selecting one of its entries. Suggestions appear inline, the user moves with arrow keys, Enter commits. Examples: station picker, customer lookup, setting finder, command palette.

For free-text queries that submit to a results page or filter a list elsewhere on the surface — no inline suggestions — use a plain TextField with type="search" and showClearButton. Don't reach for Search just because the verb is the same.

Sizes.

Two heights. Match the search to its surroundings: prominent on empty surfaces, compact in toolbars.

States.

Idle, filled, error, disabled, loading. The hairline ring thickens to 2 px on focus without shifting the input's content — focus state is a ring, not a width change.

Grouped suggestions.

Pass groups when the listbox mixes sources. Each group gets a quiet eyebrow heading; arrow keys still traverse a single flattened list, so the user never has to think about the grouping.

As a command palette.

Same combobox, different content. Add a leading icon for each row's domain, a trailing kbd for the shortcut, and you get a finder without inventing a new component.

Asynchronous queries.

For server-backed searches, debounce the query and pass loading while the request is in flight. The spinner takes the search icon's slot so the input doesn't reflow while results stream in.

Empty state.

When the query has no matches, the listbox shows a single quiet line. Default copy is “No matches.”; override emptyMessageto add a recovery action — “Add ‘Amsterdaam’ as a new alias” or a link to fuller search.

Anatomy.

Three parts on the input row itself; the listbox and helper line sit on either side of it. The listbox is the headline element — every other piece exists to serve typing into it.

Behavior.

• 01The menu opens on focus + content. The listbox appears whenever the input is focused AND there's something to show — either non-empty suggestions or a non-empty query (so the empty-state line can render). An empty input focused into a fresh page won't flash an empty menu.
• 02Selecting doesn't mutate the input. onSelect hands the suggestion to the parent; the parent decides whether to write its label back into the field, navigate away, or do something else entirely. This keeps the component honest about who owns state.
• 03Highlight resets to the first enabled option. Every time suggestions change, the highlight jumps back to the top. The user can press Enter immediately — no second ArrowDown — and they get the most-likely match.
• 04Escape clears in two stages. Esc with the menu open closes the menu but leaves the value in place. Esc again — menu closed, value present — clears the field. Native browser behaviour, just made explicit.
• 05Mouse hover and keyboard highlight are the same state. Moving the mouse over an option moves the highlight; pressing ArrowDown moves it too. There's no separate “mouse focus” rectangle, so the eye and the cursor never disagree.

Accessibility.

Search implements the WAI-ARIA 1.2 combobox pattern. role="combobox" sits on the input itself, not the wrapper, with aria-expanded and aria-controls wired to the listbox below. Keyboard focus stays in the input; aria-activedescendant points the screen reader at the highlighted option without moving DOM focus.

• ↑ ↓Move the highlight; opens the menu if closed.
• Home / EndJump to the first or last enabled suggestion.
• EnterCommit the highlighted suggestion. No-op when nothing is highlighted.
• EscClose the menu, then clear the input on a second press.
• TabClose the menu and move focus to the next control. Never hijacked.

Code.

Two patterns. The first is fully synchronous — pre-loaded data filtered in the browser. The second debounces against a remote endpoint with an in-flight token to avoid stale results.

Synchronous

import { Search, type SearchSuggestion } from "@flatpay-dk/ui";

const stations: SearchSuggestion[] = [
  { id: "ams-cs", label: "Amsterdam Centraal", description: "Stationsplein, Amsterdam" },
  { id: "ut-cs",  label: "Utrecht Centraal",   description: "Stationshal, Utrecht" },
  // …
];

function StationPicker() {
  const [query, setQuery] = React.useState("");
  const [picked, setPicked] = React.useState<SearchSuggestion | null>(null);

  const matches = stations.filter((s) =>
    s.label.toLowerCase().includes(query.trim().toLowerCase()),
  );

  return (
    <Search
      placeholder="Search stations"
      value={query}
      onValueChange={setQuery}
      suggestions={matches}
      onSelect={(s) => {
        setPicked(s);
        setQuery(s.label);
      }}
    />
  );
}

Debounced async

import { Search } from "@flatpay-dk/ui";

function CustomerSearch() {
  const [query, setQuery] = React.useState("");
  const [results, setResults] = React.useState<SearchSuggestion[]>([]);
  const [loading, setLoading] = React.useState(false);
  const tokenRef = React.useRef(0);

  React.useEffect(() => {
    if (!query) {
      setResults([]);
      return;
    }
    setLoading(true);
    const token = ++tokenRef.current;
    const handle = window.setTimeout(async () => {
      const next = await api.searchCustomers(query);
      // Drop stale responses.
      if (token !== tokenRef.current) return;
      setResults(next);
      setLoading(false);
    }, 300);
    return () => window.clearTimeout(handle);
  }, [query]);

  return (
    <Search
      placeholder="Find a customer"
      value={query}
      onValueChange={setQuery}
      suggestions={results}
      loading={loading}
      onSelect={(s) => router.push(`/customers/${s.id}`)}
      emptyMessage={
        <>
          No customer matches &ldquo;{query}&rdquo;.{" "}
          <a href="/customers/new" className="underline">
            Create one
          </a>
          .
        </>
      }
    />
  );
}

Best practices.

stations.filter(s =>
  s.label.toLowerCase()
    .includes(query.toLowerCase())
)

Props.

Related.