# Search dialog
A search that opens in a modal dialog, with the field at the top, results as you type, and key hints at the bottom. Use it for site or documentation search. For filtering a list on the page, use [Search](/components/search.md).
```tsx
// demo.tsx
import {KeyboardKey, SearchDialog, Text} from '@earendil-works/elanor-react';
import {useState} from 'react';
const pages = [
{
href: '#getting-started',
section: 'Guides',
title: 'Getting started',
excerpt: 'Install the command-line tool, sign in, and create your first project.',
},
{
href: '#deploying',
section: 'Guides',
title: 'Deploying a project',
excerpt: 'Every project deploys from its default branch. Connect a repository first.',
},
{
href: '#rollbacks',
section: 'Guides',
title: 'Rollbacks',
excerpt: 'A deploy that fails its checks never replaces the running version.',
},
{
href: '#configuration',
section: 'Reference',
title: 'Configuration file',
excerpt: 'Settings for builds, environments, and domains, in one file at the project root.',
},
];
export default function SearchDialogDemo() {
const [query, setQuery] = useState('');
const terms = query.trim().toLowerCase();
const results = terms
? pages.filter((page) => `${page.title} ${page.excerpt}`.toLowerCase().includes(terms))
: [];
return (
open && setQuery('')}>
Search documentation
{terms ? `${results.length} ${results.length === 1 ? 'result' : 'results'}` : ''}
{terms && results.length === 0 ? (
No results for “{query.trim()}”.
) : null}
{terms ? null : (
Search guides and reference pages.
)}
{results.map((page) => (
{page.section}{page.title}{page.excerpt}
))}
↑↓ to move
↵ to open
Esc to close
);
}
```
## Usage
```tsx
import {SearchDialog} from '@earendil-works/elanor-react';
Search documentation;
```
The application finds the results; the dialog shows them. Control the query with `value` and `onValueChange` on the Popup, render a `Result` per match, and show a `Message`, such as an [Empty state](/components/empty-state.md), when there are none. `Status` announces the count to assistive technology. Clear the query when the dialog opens, in Root's `onOpenChange`, so each search starts empty.
The field is a combobox that controls the list. The first result is selected as results arrive; the arrow keys move the selection, and Enter or a click follows the selected result's link and closes the dialog. A click with a modifier key, such as opening the link in a new tab, leaves it open, and so does ⌘, Ctrl, or Alt with Enter, which opens the selected result in a new tab. Without results, Enter submits the form, so set `action` and the field's `name` for a search page.
Results are `a` elements. For a router's link component, pass it as `render`, such as `render={}`; it receives the Result's `href`.
The dialog sits `semantic.dimension.space.padding.xxxxLarge` from the top, so results grow downward without moving the field, and it is as wide as [Modal](/components/modal.md). It grows with its results up to `semantic.dimension.size.maxHeight.searchDialog`, or the window if shorter. Only the results scroll, in a [Scroll area](/components/scroll-area.md), so the scrollbar overlays them instead of narrowing them. The query uses `semantic.typography.ui.searchDialog.input`, one step above the UI text.
## Keyboard shortcut
The Trigger looks like a search field. The application chooses the keyboard shortcut that opens the dialog: create a handle with `SearchDialog.createHandle()`, pass it to Root, and call `open(null)` from a key listener. Show the keys in the Trigger with `shortcut`, such as a [Keyboard shortcut](/components/keyboard-shortcut.md), and name them in `aria-keyshortcuts`. The shortcut and the Footer's hints show only on devices that hover, which usually have a keyboard.
```tsx
// keyboard-shortcut.tsx
import {KeyboardKey, KeyboardShortcut, SearchDialog, Text} from '@earendil-works/elanor-react';
import {useEffect, useState} from 'react';
const searchDialog = SearchDialog.createHandle();
export default function SearchDialogKeyboardShortcutDemo() {
const [query, setQuery] = useState('');
// The application owns the shortcut: here, Ctrl+K or ⌘K opens the search.
useEffect(() => {
function onKeyDown(event: KeyboardEvent) {
if (event.defaultPrevented || event.isComposing) return;
if ((event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 'k') {
event.preventDefault();
searchDialog.open(null);
}
}
document.addEventListener('keydown', onKeyDown);
return () => document.removeEventListener('keydown', onKeyDown);
}, []);
return (
open && setQuery('')}>
CtrlK
}
>
Search documentation
{query.trim()
? `No results for “${query.trim()}”.`
: 'Search guides and reference pages.'}
);
}
```
## Static rendering
On pages rendered on the server without React in the browser, use the static parts. `Form`, `Footer`, and `Hint` stay the same. The results come from a source in the page's script instead of React:
```tsx
Search documentation
Search guides and reference pages.
No results for “
”.
```
```ts
import {
createModal,
createScrollArea,
createSearchDialog,
enhance,
} from '@earendil-works/elanor-react';
const source = {
load: () => loadIndex(),
search: (query) => index.search(query), // [{url, context, title, excerpt}, …]
};
enhance({
modal: createModal,
'scroll-area': createScrollArea,
'search-dialog': (element) => createSearchDialog(element, source),
});
```
The popup is a native modal dialog, opened and closed like [Modal](/components/modal.md)'s static parts. Each opening starts with an empty query; the source loads when the dialog first opens, and up to ten results show once the query has two characters, the first selected. `StaticMessage`s show per state: `idle`, `short`, `loading`, `empty`, and `error`. Keyboard shortcuts are the page's: open the dialog by clicking its trigger, such as with `trigger.click()`, so it animates like any other opening. Give `StaticRoot` an `id` to open the dialog from other buttons too, with `commandfor` and `command="show-modal"`, and pass the page's own behaviors to `StaticPopup` in `data-elanor`.
## API
### `SearchDialog.Root`
A search that opens in a modal dialog. Put a `Trigger` and a `Popup` inside. To open it with a keyboard shortcut, pass a `handle` from `createHandle()` and call `open()` from the application.
Accepts Base UI [`Dialog.Root`](https://base-ui.com/react/components/dialog.md) props.
### `SearchDialog.Trigger`
Opens the dialog. It looks like a search field, with its text as the placeholder.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | The trigger's text, such as "Search documentation". |
| `shortcut` | `ReactNode` | - | A keyboard shortcut shown at the end on devices that hover, such as a `KeyboardShortcut`. It only shows the keys: the application listens for them, and names them in `aria-keyshortcuts`. |
Also accepts Base UI [`Dialog.Trigger`](https://base-ui.com/react/components/dialog.md) props.
### `SearchDialog.Popup`
The dialog, near the top of the window over a backdrop. Its parts are the `Form`, the `Results`, and the `Footer`, in that order. The field is a combobox that controls the results; the first result is selected as results arrive, and the arrow keys move the selection.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` (required) | `string` | - | The accessible name, such as "Search documentation". |
| `children` | `ReactNode` | - | |
Also accepts Base UI [`Autocomplete.Root`](https://base-ui.com/react/components/autocomplete.md) props.
### `SearchDialog.Form`
The top row, a search form: holds the `Input` and a `Close`. Without results, Enter submits.
Renders `