Components

Command

A command palette on a slip of paper. Type and the list is sorted and cut down (cmdk's fuzzy match); the row you are on wears the highlighter, keys show as pencil keycaps, an empty search gets Stubby with his magnifier. Put it in a dialog and it is set on a napkin.

Install

terminal
npx shadcn@latest add @wobko/command

First time here? Add the registry to components.json first. How to install

Examples

Default

The shadcn demo on a slip. Type to cut the list down ("cal"), use the arrow keys, Enter to choose. The row you are on wears the highlighter; Calculator is disabled; the last three end in a keycap.

In a dialog, on a napkin

Press Ctrl + K (or Cmd + K) anywhere, or the button. The palette is set on a napkin with a pinked edge, over the dim; Escape puts it away and focus goes back to the button.

Empty and loading

Results that come from a server: filtering is off (`shouldFilter={false}`), the loops show while a search is on its way, and Stubby comes out with his magnifier when the answer is nothing. Try "inv", then "zzz".

A status picker in a popover

The classic use: a Command inside a Popover. The popover is the paper (the palette's own slip switches itself off), the chosen status gets a tick, and picking one closes the slip.

API reference

Command

The palette (cmdk `Command`): every cmdk prop works (`value`, `onValueChange`, `filter`, `shouldFilter`, `loop`, `label`...). It lies on a slip of paper of its own, which switches itself off inside a Popover, Dialog, Card, Sheet or Drawer that already is paper. Like upstream's it is `h-full w-full`: put it in a box with a height, or pass `className="h-auto"` (in a container that only has a `min-height` WebKit resolves `100%` against that and stretches the slip).

PropTypeDefaultDescription
sheetboolean | { stock, edge, tilt, tape, tapeKind, shadow, seed }trueThe slip under the palette. `false` draws none; an object picks another stock (`{ stock: "napkin" }`).
labelstring-Accessible name (cmdk keeps it in a screen-reader-only label).

CommandDialog

The palette in a Dialog, set on a napkin with a pinked edge, pinned near the top of the window (a centered sheet would move the search field under your eyes as the list grows and shrinks; `className` overrides it). The title and description are for screen readers only. Opening it with a shortcut (Ctrl / Cmd + K) is yours to wire (see the example).

PropTypeDefaultDescription
title / descriptionstring"Command Palette" / "Search for a command to run..."The dialog's accessible name and description.
showCloseButtonbooleanfalseThe corner x. Off by default (upstream: on): a palette closes with Escape or a click outside.
stock / edge / tape / tilt / seedPaperPropsstock "napkin"What the sheet is made of and how it is cut; passed to the dialog's Paper.
commandPropsOmit<CommandProps, 'children'>-Props for the Command inside (`shouldFilter`, `filter`, `loop`, `value`...).

CommandInput

The search field: a magnifier, blue felt text, a double rule drawn under the row (a blue one joins it when the field has focus). One ink drawing, on the wrapper; the input is a plain direct child. A polite status says how many results are left.

PropTypeDefaultDescription
resultsLabel(count: number) => string"No results" | "1 result" | "n results"Text of the screen-reader status (translate it). It stays empty until something is typed.
wrapperClassNamestring-Classes for the row around the input.
seedstring | number-Pins the hand that draws the rule.

CommandEmpty

Shown by cmdk when nothing matches: Stubby with his magnifier and your words in script. Write it inside `CommandList` as usual; it is drawn just below the (empty) listbox so the listbox stays valid.

PropTypeDefaultDescription
mascotbooleantrue`false` leaves Stubby out.

Accessibility

  • cmdk: the input is a `role=combobox` with `aria-controls` and `aria-activedescendant`; the list is a `role=listbox` of `role=option` rows with `aria-selected` and `aria-disabled`. Focus stays in the input; the arrow keys move the highlight, Home and End jump, Enter chooses, and `loop` wraps.
  • Ctrl + N / P / J / K also move the highlight (cmdk's vim bindings; `vimBindings={false}` turns them off).
  • A polite status under the search field says "3 results" or "No results" after each keystroke, which cmdk does not do by itself. The empty message is shown as well.
  • The highlighted row is a highlighter-yellow shape, not only a hue; a disabled row is graphite and dimmed but still readable.
  • CommandDialog is a Radix dialog: focus goes into the input and Escape closes. Radix returns focus only to a `DialogTrigger`; a palette opened by a shortcut or a button that sets `open` has none, so CommandDialog remembers who had the focus when it opened and gives it back when it closes, unless the app has moved it on by then (choose a result, go to that page, and the focus stays on the new page's heading instead of jumping back to the button). Its title and description are `sr-only`.
  • The input's `aria-activedescendant` always names the selected row: cmdk records it before it has redrawn the rows, so after typing it could name a row that was gone; `CommandInput` corrects it after every keystroke. If you render cmdk's `Command.Input` yourself inside a `Command`, call `useFreshActiveDescendant(inputRef)` from this file.
  • Reduced motion: no drop-in or zoom, and no loop animation in Loading. Forced colors: the rule under the field becomes a real border and the highlighted row gets a Highlight background.

Source

The files the CLI copies into your project.

Loading the source