CommandPalette

Modal, keyboard-driven command launcher: a search input filters a listbox of commands (matched on label + keywords); Arrow keys move the active option, Enter runs it, Escape closes. Focus is trapped and background scroll locked while open.

Status: beta. Group: navigation. Markdown version: /design-system/components/command-palette.md

When to use

CommandPalette is a modal, keyboard-first launcher: a search input filters a listbox of commands matched on label and keywords, Arrow keys move the active option, Enter runs it, Escape closes. It is controlled (open + onClose) and portal-rendered with focus trapped and background scroll locked while open. Reach for it as a power-user shortcut surface (go-to navigation, quick actions), not as a replacement for primary navigation or a container for forms. All user-facing strings are props so the host owns i18n.

When not to use

Do not nest submenus or put long forms inside it; it is a launcher, not a menu system or a modal form.
Do not hardcode user-facing copy; pass label, placeholder, and emptyText so the host owns i18n.

Look-alikes

The contract names no look-alike with a deciding condition.

Props

CommandPalette props
Prop	Type	Default	Description	Required
`open`	`boolean`	none	Whether the palette is open (controlled).	Yes
`onClose`	`() => void`	none	Called to request close (Escape, overlay click, or after a selection).	Yes
`items`	`CommandPaletteItem[]`	none	Commands to show, in order.	Yes
`label`	`string`	Command palette	Accessible name for the dialog + listbox.	No
`placeholder`	`string`	Search commands…	Search input placeholder.	No
`emptyText`	`string`	No results	Shown when nothing matches.	No
`className`	`string`	none	Additional CSS class names for the dialog.	No

Variants

No variant dimensions and no props with a fixed set of values.

Invalid combinations

The contract records no invalid combinations.

Keyboard

CommandPalette keyboard behaviour
Key	Behaviour
Arrow Down / Up	Move the active option (wrapping)
Enter	Runs the active command and closes.
Escape	Closes the palette.
General	Focus is trapped within the dialog while open.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

CommandPalette rules
Level	Rule	How it is checked
MUST	ARIA: Overlay dialog is role=dialog aria-modal with an accessible label.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Input is role=combobox with aria-controls + aria-activedescendant onto the listbox.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Each command is role=option with aria-selected reflecting the active item.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	Every documented keyboard interaction works as specified.	Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-07-12.

Install and import

Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
Import: import { CommandPalette } from "@digitaltableteur/react";
Entry point: @digitaltableteur/react/navigation exports it too.
Styles: import @digitaltableteur/react/style.css once at the app boundary.
Also available as the custom element <dt-command-palette>; see the custom elements manifest.