Command · ui.voila.dev

Usage

import { Command } from "@voila.dev/ui/command";

<Command.Root>
	<Command.Input placeholder="Search projects, freelancers…" />
	<Command.List>
		<Command.Empty>No results found.</Command.Empty>
		<Command.Group heading="Projects">
			<Command.Item>
				<CalendarIcon />
				Launch review — Saturday
			</Command.Item>
		</Command.Group>
	</Command.List>
</Command.Root>

A filterable list of commands — the ⌘K palette. It is worth adding once an app has more actions than a person can find by looking, and it is dead weight before that. Command.Dialog is the palette in a modal, which is how it is almost always used; the bare Command embeds the same list in a page or a Popover, which is what Combobox is built on.

Recipes

Command.Dialog takes a title and description that are visually hidden and read by screen readers — the input is the visible cue, but the dialog still needs naming. It is controlled the same way as Dialog, so binding it to ⌘K is a key handler and an open prop.

Group items with Command.Group, and give each a Command.Shortcut where a direct key exists, so the palette teaches the shortcuts rather than replacing them.

API

Command.Root

Prop	Type	Default
`asChild`	`boolean`	—
`children`	`ReactNode`	—
`defaultValue`	`string \| (readonly string[] & string)`	—	Optional default item value when it is initially rendered.
`disablePointerSelection`	`boolean`	—	Optionally set to `true` to disable selection via pointer events.
`filter`	`CommandFilter`	—	Custom filter function for whether each command menu item should matches the given search query. It should return a number between 0 and 1, with 1 being the best match and 0 being hidden entirely. By default, uses the `command-score` library.
`label`	`string`	—	Accessible label for this command menu. Not shown visibly.
`loop`	`boolean`	—	Optionally set to `true` to turn on looping around when using the arrow keys.
`onValueChange`	`((value: string) => void)`	—	Event handler called when the selected item of the menu changes.
`shouldFilter`	`boolean`	—	Optionally set to `false` to turn off the automatic filtering and sorting. If `false`, you must conditionally render valid items based on the search query yourself.
`value`	`string`	—	Optional controlled state of the selected command menu item.
`vimBindings`	`boolean`	—	Set to `false` to disable ctrl+n/j/p/k shortcuts. Defaults to `true`.

Plus the DOM props of the element it renders. Source: command/components/command-root.tsx.

The undescribed props here come from cmdk, which this is built on; its documentation covers filter, shouldFilter, loop and the others.

Command.Dialog

Prop	Type	Default
`children`	`ReactNode`	required	The `Command` tree: input, list, groups and items.
`className`	`string`	—	Classes for the dialog panel.
`description`	`string`	`"Search for a command to run..."`	Accessible description, also visually hidden.
`showCloseButton`	`boolean`	`false`	Draws the X in the corner.
`title`	`string`	`"Command Palette"`	Accessible name of the dialog. Visually hidden — the input is the visible cue.
`actionsRef`	`RefObject<DialogRootActions \| null>`	—	A ref to imperative actions.
`defaultOpen`	`boolean`	—	Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead.
`defaultTriggerId`	`string \| null`	—	ID of the trigger that the dialog is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog.
`disablePointerDismissal`	`boolean`	—	Whether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it.
`handle`	`DialogHandle<unknown>`	—	A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog's open state. Can be created with the Dialog.createHandle() method.
`modal`	`"trap-focus" \| boolean`	—	Determines if the dialog enters a modal state when open. When `modal` is `true` or `'trap-focus'`, render `<Dialog.Close>` inside `<Dialog.Popup>` so touch screen readers can escape the popup.
`onOpenChange`	`((open: boolean, eventDetails: DialogRootChangeEventDetails) => void)`	—	Event handler called when the dialog is opened or closed.
`onOpenChangeComplete`	`((open: boolean) => void)`	—	Event handler called after any animations complete when the dialog is opened or closed.
`open`	`boolean`	—	Whether the dialog is currently open.
`triggerId`	`string \| null`	—	ID of the trigger that the dialog is associated with. This is useful in conjunction with the `open` prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set).

Plus the DOM props of the element it renders. Source: command/components/command-dialog.tsx.

Command.Empty

Prop	Type	Default
`asChild`	`boolean`	—
`children`	`ReactNode`	—

Plus the DOM props of the element it renders. Source: command/components/command-empty.tsx.

Command.Group

Prop	Type	Default
`asChild`	`boolean`	—
`children`	`ReactNode`	—
`forceMount`	`boolean`	—	Whether this group is forcibly rendered regardless of filtering.
`heading`	`ReactNode`	—	Optional heading to render for this group.
`value`	`string`	—	If no heading is provided, you must provide a value that is unique for this group.

Plus the DOM props of the element it renders. Source: command/components/command-group.tsx.

Command.Input

Prop	Type	Default
`asChild`	`boolean`	—
`onValueChange`	`((search: string) => void)`	—	Event handler called when the search value changes.
`value`	`string`	—	Optional controlled state for the value of the search input.

Plus the DOM props of the element it renders. Source: command/components/command-input.tsx.

Command.Item

Prop	Type	Default
`asChild`	`boolean`	—
`children`	`ReactNode`	—
`disabled`	`boolean`	—	Whether this item is currently disabled.
`forceMount`	`boolean`	—	Whether this item is forcibly rendered regardless of filtering.
`keywords`	`string[]`	—	Optional keywords to match against when filtering.
`onSelect`	`((value: string) => void)`	—	Event handler for when this item is selected, either via click or keyboard selection.
`value`	`string`	—	A unique value for this item. If no value is provided, it will be inferred from `children` or the rendered `textContent`. If your `textContent` changes between renders, you must provide a stable, unique `value`.

Plus the DOM props of the element it renders. Source: command/components/command-item.tsx.

Command.List

Prop	Type	Default
`asChild`	`boolean`	—
`children`	`ReactNode`	—
`label`	`string`	—	Accessible label for this List of suggestions. Not shown visibly.

Plus the DOM props of the element it renders. Source: command/components/command-list.tsx.

Command.Separator

Prop	Type	Default
`alwaysRender`	`boolean`	—	Whether this separator should always be rendered. Useful if you disable automatic filtering.
`asChild`	`boolean`	—

Plus the DOM props of the element it renders. Source: command/components/command-separator.tsx.

Command.Shortcut

Prop	Type	Default
`keys`	`readonly string[]`	—	Render each key as a small `Kbd` chip. Omit it and children are shown as plain text.

Plus the DOM props of the element it renders. Source: command/components/command-shortcut.tsx.

Combobox · Dialog · Kbd · DropdownMenu