Command

A command menu lists actions and filters them while users type in its search input. Users move through the results with the arrow keys and run the selected item with Enter or a click, so they reach an action without leaving the keyboard. When no item matches the search, the menu shows its empty message.

UsageCopy Anchor Link

import {
	Command,
	CommandEmpty,
	CommandGroup,
	CommandInput,
	CommandItem,
	CommandList,
} from "@biem/ui/components/ui/command";

export function CommandDefault() {
	return (
		<Command className="max-w-sm">
			<CommandInput placeholder="Search actions..."/>
			<CommandList>
				<CommandEmpty>No actions found.</CommandEmpty>
				<CommandGroup heading="Inventory">
					<CommandItem>Create transfer</CommandItem>
					<CommandItem>Receive delivery</CommandItem>
					<CommandItem>Start inventory count</CommandItem>
				</CommandGroup>
			</CommandList>
		</Command>
	);
}

ExamplesCopy Anchor Link

With SeparatorCopy Anchor Link

Related actions are easier to find when they stand together, and a menu with several groups reads more calmly when a boundary divides them. A separator marks that boundary while the search is empty. As soon as users type, it disappears, and only the matching items and their groups remain.

With IconsCopy Anchor Link

In a menu that users open many times a day, an icon lets them recognize a familiar action before they read its words. The search still matches the text of each item, so users find every action by name, whatever its icon.

With ShortcutsCopy Anchor Link

Frequent actions deserve a faster route than the search. A CommandShortcut in the item names the key combination for its action, so users learn it while they search and can skip the menu next time. It only displays the keys, and the application itself must listen for them.

DialogCopy Anchor Link

Users reach a command menu fastest when it is available from every page instead of one place only. Inside CommandDialog, the menu opens above the current page and keeps the focus until users close it with Escape or a press outside. The example also closes it when users run an action, so they return to their work at once. Its title and description stay invisible, yet they tell assistive technology what the dialog offers.

Selected by DefaultCopy Anchor Link

Often one action is the likely next step of a workflow. With defaultValue, the item of that action is already selected when the menu appears, so users run it with Enter right away. As soon as they type, the selection moves to the best match.

Controlled SelectionCopy Anchor Link

An application sometimes needs to know which item users are considering before they run it, for example to explain what the action will change. Held in value and onValueChange, the selection belongs to the application, which can also move it from elsewhere in the interface.

Controlled SearchCopy Anchor Link

Context often suggests a search before users type, for example when they open the menu from a page about a single article. Through value and onValueChange of CommandInput, the application holds the search text, so it can fill it in beforehand, clear it, or keep it for the next time users open the menu.

Without ResultsCopy Anchor Link

A search that finds nothing still owes users an answer, or they wonder whether the menu has stopped working. Only when no item matches does CommandEmpty appear, and its message makes clear that the search ran without a match, so users rephrase it instead of waiting.

Disabled ItemCopy Anchor Link

Some actions are unavailable for a while, such as a price update that still waits for approval. The item stays visible, in the search results as well, so users know that the action exists. With disabled, however, they can neither select nor run it, the arrow keys pass over it, and assistive technology announces it as unavailable.

Checked ItemCopy Anchor Link

A command menu also serves as a picker, for example when users switch the period a report covers, and then users need to see which option is active. Set to true on the item of the current choice, data-checked marks it, and the application moves that mark when users pick another option.

With KeywordsCopy Anchor Link

Users often search with their own words, such as an abbreviation or a term from another department, and these words may differ from the label of an action. Additional terms in keywords make an item match those words as well, while its label stays the same.

Custom FilterCopy Anchor Link

By default, the search matches loosely: the typed letters only need to appear in the same order, so a few of them find an item even when they are spread across its words. Where users expect stricter results, such as article numbers that must match from the first digit, filter replaces that rule with one of the application's own, which also decides the order of the matching items.

Manual FilteringCopy Anchor Link

A large catalog cannot be loaded into the menu at once, so a server returns the matching articles while users type. Once shouldFilter is set to false, the menu shows the items it receives in the order it receives them, and the arrow keys, Enter and the empty message work as before.

With FrameCopy Anchor Link

Placed directly in a page rather than in a dialog or a popover, the menu needs a boundary that separates it from the surrounding content. Enclosed in CommandFrame, it shows users at once where the search and its results begin and end.

API ReferenceCopy Anchor Link

CommandCopy Anchor Link

CommandDialogCopy Anchor Link

CommandInputCopy Anchor Link

CommandListCopy Anchor Link

CommandEmptyCopy Anchor Link

CommandGroupCopy Anchor Link

CommandSeparatorCopy Anchor Link

CommandItemCopy Anchor Link

CommandShortcutCopy Anchor Link

CommandShortcut shows the keyboard shortcut of an item at the end of the item. It only displays the keys and doesn't listen for them. It renders a span and has no props of its own.