Command

A command palette for searching and executing actions. Built on cmdk.

Installation

$
npx shadcn@latest add https://ui.mattdowney.com/r/command.json

Usage

import { Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandItemMedia, CommandItemMeta, CommandShortcut } from "@/components/ui/command"

Examples

Default

The palette inline rather than in a dialog, for a search panel that lives on the page. Typing filters and ranks the items for you; pass shouldFilter={false} when the results come from a server.

Dialog (⌘K)

The modal palette. position="top" pins it near the top so the input stays put as results change, and footer holds the key hints. For server results pass commandProps={{ shouldFilter: false }}.

Search results

A row per result: CommandItemMedia for the cover, the title, and CommandItemMeta for the topic, which brightens with the highlighted row. The trigger shows its shortcut with Kbd.

API Reference

PropTypeDefaultDescription
titleCommandDialogstring"Command Palette"Screen-reader title for the palette, rendered visually hidden.
descriptionCommandDialogstring"Search for a command to run..."Screen-reader description for the palette, rendered visually hidden.
showCloseButtonCommandDialogbooleantrueShows the close button in the dialog's top-right corner.
positionCommandDialog"center" | "top""center"top pins the window near the top of the viewport and grows it downward only, so a changing result count never moves the input. Its list defaults to the tall height.
footerCommandDialogReact.ReactNodeNoneA row under the list for key hints, built from KbdHint. Its sides line up with the rows' content, 16px in. Hidden on touch pointers, which have no keys.
commandPropsCommandDialogOmit<CommandProps, "children">NoneForwarded to the inner Command: shouldFilter, loop, filter, a controlled value. Pass { shouldFilter: false } when a server supplies the results.
shouldFilterCommandbooleantrueWhether cmdk filters and ranks items against the search query. Set false to filter results yourself.
filterCommand(value, search, keywords) => numberNoneCustom ranking function; return 0 to hide an item, higher scores rank first.
loopCommandbooleanfalseWraps keyboard navigation from the last item back to the first.
heightCommandList"default" | "tall""default"The list's height cap before it scrolls: default is 300px, tall is 40% of the viewport. Defaults to tall inside a top-positioned CommandDialog.
headingCommandGroupReact.ReactNodeNoneLabel rendered above the group's items.
valueCommandItemstringNoneExplicit value used for filtering and selection; defaults to the item's text content.
onSelectCommandItem(value: string) => voidNoneCalled when the item is chosen via click or Enter.
disabledCommandItembooleanfalseDisables the item so it can't be selected.
srcCommandItemMediastringNoneImage for the 20px square at the start of a row. Or pass your own image element as children; the box is relative, so a framework image with fill works. With neither, the muted square holds the space.
altCommandItemMediastring""Empty by default: the row's label already names the image. Set it only when the image says something the label does not.
childrenCommandItemMetaReact.ReactNodeNoneWords at the end of a row, such as a topic or a type. Muted, one size below the label, and foreground while the row is highlighted. For key glyphs use CommandShortcut.
titleCommandDialogstring = "Command Palette"Screen-reader title for the palette, rendered visually hidden.
descriptionCommandDialogstring = "Search for a command to run..."Screen-reader description for the palette, rendered visually hidden.
showCloseButtonCommandDialogboolean = trueShows the close button in the dialog's top-right corner.
positionCommandDialog"center" | "top" = "center"top pins the window near the top of the viewport and grows it downward only, so a changing result count never moves the input. Its list defaults to the tall height.
footerCommandDialogReact.ReactNodeA row under the list for key hints, built from KbdHint. Its sides line up with the rows' content, 16px in. Hidden on touch pointers, which have no keys.
commandPropsCommandDialogOmit<CommandProps, "children">Forwarded to the inner Command: shouldFilter, loop, filter, a controlled value. Pass { shouldFilter: false } when a server supplies the results.
shouldFilterCommandboolean = trueWhether cmdk filters and ranks items against the search query. Set false to filter results yourself.
filterCommand(value, search, keywords) => numberCustom ranking function; return 0 to hide an item, higher scores rank first.
loopCommandboolean = falseWraps keyboard navigation from the last item back to the first.
heightCommandList"default" | "tall" = "default"The list's height cap before it scrolls: default is 300px, tall is 40% of the viewport. Defaults to tall inside a top-positioned CommandDialog.
headingCommandGroupReact.ReactNodeLabel rendered above the group's items.
valueCommandItemstringExplicit value used for filtering and selection; defaults to the item's text content.
onSelectCommandItem(value: string) => voidCalled when the item is chosen via click or Enter.
disabledCommandItemboolean = falseDisables the item so it can't be selected.
srcCommandItemMediastringImage for the 20px square at the start of a row. Or pass your own image element as children; the box is relative, so a framework image with fill works. With neither, the muted square holds the space.
altCommandItemMediastring = ""Empty by default: the row's label already names the image. Set it only when the image says something the label does not.
childrenCommandItemMetaReact.ReactNodeWords at the end of a row, such as a topic or a type. Muted, one size below the label, and foreground while the row is highlighted. For key glyphs use CommandShortcut.