Search Dialog
A quick search: search by keyword and pick from a list, in a modal (the
pattern is also marketed as “command palette”, but nothing here is a command).
It composes the Dialog (native <dialog> element, scroll lock, Escape / backdrop
close, focus restore) and the Combobox (search, filter, keyboard) — no new
core code. What it searches is up to the application: content, pages, files,
people, or the service’s own actions and features.
Give items a group (“Pages”, “Actions”) to section the results by type
under a header, like a product-wide quick search: ungrouped results come first,
groups follow in order of first appearance, and a group whose results are all
filtered out disappears with its header. Keyboard traversal is flat — arrows
cross group boundaries in display order.
suggestions are shown while the query is empty — recents, frequent
searches: the application measures and decides, the dialog displays (they may
carry their own group, e.g. “Recent”). Set loading while results are
fetched: an indicator appears, the status region announces “Searching…”, and
the empty state waits; feed the async results through items when they arrive.
Items can carry a shortcut (“⌘S” or ["⌘", "S"] for a chord), rendered
right-aligned as a keycap. It is a label, not a binding: the dialog never
registers keyboard shortcuts — live shortcuts belong to the application, like
the one that opens it. No open shortcut is built in either: bind open and
wire it in the application (the demo above uses ⌘S /
Ctrl+S).
Unlike the family’s simple dialogs, it asks nothing and interrupts nothing — it is a search tool inside the same modal shell.
When to use which dialog
Section titled “When to use which dialog”- Dialog — generic modal for any content; the head of the family.
- Alert Dialog — an acknowledgement: a message with nothing to cancel (one button).
- Confirm Dialog — verify or accept before proceeding:
cancel stops, confirm proceeds (
urgentto interrupt). - Prompt Dialog — asks for a single value
(optional,
required, or gated byconfirmValue;urgentto interrupt). - Search Dialog — a quick search: search by keyword and pick from a list.
- Sheet Dialog — a task in an edge-anchored panel
(
sidevariant, optional drag-to-dismiss).
Import
Section titled “Import”<script> import SearchDialog from "@invisible-ui/svelte/SearchDialog.svelte";</script><script setup> import { SearchDialog } from "@invisible-ui/vue";</script>import { SearchDialog } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-search-dialog></ds-search-dialog>In Elements, assign the results as a property and listen for select:
<ds-search-dialog trigger="Search…" placeholder="Search pages and actions"></ds-search-dialog>
<script type="module"> const search = document.querySelector("ds-search-dialog"); search.items = [ { value: "home", label: "Home", group: "Pages" }, { value: "save", label: "Save", group: "Actions", shortcut: ["⌘", "S"] }, ]; search.suggestions = [{ value: "home", label: "Home", group: "Recent" }]; search.addEventListener("select", (event) => run(event.detail.value));</script>The title names the dialog and stays visually hidden: hide-title="false"
shows it, and close-button adds a close button to the header.
In React, pass the results as items and read the choice in onSelect.
useSearchDialog gives the same behaviour for markup of your own:
<SearchDialog items={[ { value: "home", label: "Home", group: "Pages" }, { value: "save", label: "Save", group: "Actions", shortcut: ["⌘", "S"] }, ]} suggestions={[{ value: "home", label: "Home", group: "Recent" }]} onSelect={(value) => run(value)}/>| Prop | Type | Default | Description |
|---|---|---|---|
triggerVariant | "default" | "primary" | "secondary" | "ghost" | "danger" | "default" | Visual variant for the trigger Button. |
items * | SearchDialogItem[] | — | |
suggestions | SearchDialogItem[] | [] | Items shown while the query is empty — recents, frequent searches. The application measures and decides; the dialog displays. They may carry their own group ("Recent"). Empty means: an empty query shows all items. |
loading | boolean | false | Results are being fetched: shows an indicator, announces "Searching…" through the status region and suppresses the empty state meanwhile. Feed async results through items when they arrive. |
open | boolean | false | |
title | string | undefined | undefined | Accessible title for the dialog. Defaults to the i18n catalog's "Search". |
hideTitle | boolean | true | Visually hide the title (the default: the search field reads as the header). It still names the dialog for screen readers. |
closeButton | boolean | false | Show a close button in the header; it closes like Escape. |
closeLabel | string | undefined | undefined | Accessible label for the close button. Defaults to the i18n catalog's "Close". |
label | string | undefined | undefined | Accessible label for the search input. Defaults to the i18n catalog's "Search". |
placeholder | string | undefined | undefined | Input placeholder. Defaults to the i18n catalog's "Type to search…". |
emptyText | string | undefined | undefined | Text shown when nothing matches. Defaults to the i18n catalog's "No results found.". |
onSelect | ((value: string) => void) | undefined | undefined | |
onOpenChange | ((o: boolean) => void) | undefined | undefined | |
trigger | Snippet | undefined | undefined | The trigger button's content. Defaults to the i18n catalog's label. |
| Prop | Type | Default | Description |
|---|---|---|---|
triggerVariant | ButtonVariant | "default" | Visual variant for the trigger Button. |
trigger | string | undefined | The trigger button's label. The trigger slot replaces it with markup. |
items * | SearchDialogItem[] | — | |
suggestions | SearchDialogItem[] | () => [] | Items shown while the query is empty: recents, frequent searches. The application measures and decides; the dialog displays. They may carry their own group ("Recent"). Empty means an empty query shows all items. |
loading | boolean | false | Results are being fetched: shows an indicator, announces "Searching…" through the status region and holds back the empty state meanwhile. Feed async results through items when they arrive. |
open | boolean | false | Initial / controlled open state; bindable with v-model:open. |
title | string | undefined | Accessible title for the dialog. Defaults to the catalog's "Search". |
hideTitle | boolean | true | Visually hide the title (the default: the search field reads as the header). It still names the dialog for screen readers. |
closeButton | boolean | false | Show a close button in the header; it closes like Escape. |
closeLabel | string | undefined | Accessible label for the close button. Defaults to the catalog's "Close". |
label | string | undefined | Accessible label for the search input. Defaults to the catalog's "Search". |
placeholder | string | undefined | Input placeholder. Defaults to the catalog's "Type to search…". |
emptyText | string | undefined | Text shown when nothing matches. Defaults to the catalog's "No results found.". |
onSelect | (value: string) => void | undefined | |
onOpenChange | (open: boolean) => void | undefined |
| Event | Payload |
|---|---|
update:open | open: boolean |
Slots: trigger.
| Prop | Type | Default | Description |
|---|---|---|---|
triggerVariant | ButtonVariant | "default" | Visual variant for the trigger Button. |
trigger | ReactNode | — | The trigger button's content. Defaults to the catalog's "Search…". |
items * | SearchDialogItem[] | — | The searchable results. |
suggestions | SearchDialogItem[] | — | Items shown while the query is empty: recents, frequent searches. The application measures and decides; the dialog displays. They may carry their own group ("Recent"). Empty means an empty query shows all items. |
loading | boolean | false | Results are being fetched: shows an indicator, announces "Searching…" through the status region and holds back the empty state meanwhile. Feed async results through items when they arrive. |
open | boolean | false | Initial / controlled open state. |
title | string | — | Accessible title for the dialog. Defaults to the catalog's "Search". |
hideTitle | boolean | true | Visually hide the title (the default: the search field reads as the header). It still names the dialog for screen readers. |
closeButton | boolean | false | Show a close button in the header; it closes like Escape. |
closeLabel | string | — | Accessible label for the close button. Defaults to the catalog's "Close". |
label | string | — | Accessible label for the search input. Defaults to the catalog's "Search". |
placeholder | string | — | Input placeholder. Defaults to the catalog's "Type to search…". |
emptyText | string | — | Text shown when nothing matches. Defaults to the catalog's "No results found.". |
filter | (items: SearchDialogItem[], query: string) => SearchDialogItem[] | — | Filter results against the query. Defaults to case-insensitive substring. |
onSelect | (value: string) => void | — | Called when a result is chosen (before the dialog closes). |
onOpenChange | (open: boolean) => void | — | Called whenever the open state changes. |
| Attribute | Reactive | Description |
|---|---|---|
heading | yes | "Search" by default |
hide-title | yes | "false" shows the title |
label | yes | the input's accessible name, "Search" by default |
placeholder | yes | |
empty-text | yes | |
loading | yes | results are being fetched |
trigger | yes | opener text |
trigger-variant | yes | |
open | yes | |
close-button | yes | |
close-label | yes |
Reactive attributes re-render the element when they change after the first render.
Properties: open (boolean), items and suggestions (arrays of { value, label?, disabled?, group?, shortcut? }).
Methods: notify(options), dismissNotice(id), clearNotices() (the status area, ADR 0016).
Emits: bubbling open-change CustomEvent with detail.open, and select with detail.value when a result is chosen.
The trigger snippet is the opener button’s content.
Accessibility
Section titled “Accessibility”- A modal
role="dialog"(aria-modal) containing arole="combobox"search input over arole="listbox"of results. On open, focus moves to the input and is trapped; Escape / a backdrop press close it and restore focus. - Typing filters; Arrow Up/Down move the highlight (
aria-activedescendant), Enter selects the active result and closes. - The query is what the user wrote, so focus leaving the input changes nothing: the text stays and the palette stays open. Dismissal belongs to the dialog (Escape, a backdrop press), not to focus. This is the opposite of the Combobox, whose text is a filter over a value it must go back to.
- Grouped results sit in
role="group"containers named viaaria-label, so screen readers announce the section when entering it; the visible header is hidden from AT to avoid double reading. - A visually-hidden
role="status"region announces the filtered result count (“3 results available” / “No results found.”) on every keystroke — and “Searching…” whileloading— so screen-reader users hear the effect of their typing. - Item shortcuts are rendered with the semantic
<kbd>element (via the Kbd component) and are part of the option’s accessible name.
Example
Section titled “Example”<script> let open = $state(false); const items = [ { value: "home", label: "Home", group: "Pages" }, { value: "new", label: "New File", group: "Actions" }, { value: "save", label: "Save", group: "Actions" }, ];</script>
<svelte:window onkeydown={(e) => { if ((e.metaKey || e.ctrlKey) && e.key === "s") { e.preventDefault(); open = true; } }}/>
<SearchDialog {items} bind:open onSelect={(value) => run(value)}> {#snippet trigger()}<span>Search…</span>{/snippet}</SearchDialog>Themeable via --ds-search-dialog-* (panel width, inset, radius) plus the
shared --ds-dialog-* overlay tokens.