ExpandingSearch

A search icon that springs open into a field, with grouped, keyboard-navigable results beneath it.

When to use

• Header or toolbar search where space is tight until someone wants to search.
• Small, client-side item sets (tasks, documents, people) filtered by title, meta and keywords.
• Not for an app-wide action launcher; use CommandPalette.
• Not for large or server-ranked datasets unless you pre-filter items yourself.

Usage

import { ExpandingSearch } from "@/components/iris/expanding-search/expanding-search";

h(ExpandingSearch, {
  label: "Search tasks and documents",
  items: [
    { id: "t1", title: "Add login", group: "Tasks", meta: "Doing · p1 · Katerina Vlachou" },
    { id: "d1", title: "Seat-based pricing", group: "Documents", meta: "Decision · accepted", keywords: ["seats"] },
  ],
  suggestions: recentItems,
  onSelect: (item) => openItem(item.id),
});

Props

Prop	Type	Default	Description
label	string	required	Names the button, the field and the results.
items	ExpandingSearchItem[]	required	{ id, title, meta?, group?, icon?, keywords? }. Results gather under group headings in first-seen order.
suggestions	ExpandingSearchItem[]	[]	Shown before anything is typed, such as recent searches.
suggestionsLabel	string	"Recent"	Heading for the suggestions.
placeholder	string	label	Field placeholder.
onSelect	(item) => void	–	Fires when a result is chosen.
onExpandedChange	(expanded: boolean) => void	–	Fires when the field opens or closes.
expandedWidth	number	360	Widest the field grows; never wider than its container.
maxResults	number	6	Most results shown.
anchor	"start" | "end"	"end"	Edge the button sits on; the field grows away from it.
emptyHint	string	spelling tip	Tip under the empty state.
className	string	–	Added to the root.

Notes

• Keyboard: Enter or Space on the icon expands; arrows move through results and wrap; Enter picks; Escape collapses back to the icon.
• The field is a combobox over a grouped listbox; result counts and empty states are announced politely. The collapsed field is inert.
• Reduced motion replaces the width spring and gliding highlight with fades.
• The results panel sizes to the space available, so give it room below the header.
• Reads --surface, --hover, --line, --line-strong, --ink, --focus-ring, --shadow-floating, --radius-control, --radius-panel, --radius-button.