Command
A command palette for searching and executing actions. Built on cmdk.
Installation
$
npx shadcn@latest add https://ui.mattdowney.com/r/command.jsonUsage
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.
No results found.
Suggestions
Calendar
Search
Settings
Actions
New file
New folder
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
| Prop | Type | Default | Description |
|---|---|---|---|
| titleCommandDialog | string | "Command Palette" | Screen-reader title for the palette, rendered visually hidden. |
| descriptionCommandDialog | string | "Search for a command to run..." | Screen-reader description for the palette, rendered visually hidden. |
| showCloseButtonCommandDialog | boolean | true | Shows 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. |
| footerCommandDialog | React.ReactNode | None | A 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. |
| commandPropsCommandDialog | Omit<CommandProps, "children"> | None | Forwarded to the inner Command: shouldFilter, loop, filter, a controlled value. Pass { shouldFilter: false } when a server supplies the results. |
| shouldFilterCommand | boolean | true | Whether cmdk filters and ranks items against the search query. Set false to filter results yourself. |
| filterCommand | (value, search, keywords) => number | None | Custom ranking function; return 0 to hide an item, higher scores rank first. |
| loopCommand | boolean | false | Wraps 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. |
| headingCommandGroup | React.ReactNode | None | Label rendered above the group's items. |
| valueCommandItem | string | None | Explicit value used for filtering and selection; defaults to the item's text content. |
| onSelectCommandItem | (value: string) => void | None | Called when the item is chosen via click or Enter. |
| disabledCommandItem | boolean | false | Disables the item so it can't be selected. |
| srcCommandItemMedia | string | None | Image 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. |
| altCommandItemMedia | string | "" | Empty by default: the row's label already names the image. Set it only when the image says something the label does not. |
| childrenCommandItemMeta | React.ReactNode | None | Words 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. |
"use client"
import * as React from "react"
import { Command as CommandPrimitive } from "cmdk"
import { IconSearch as SearchIcon } from "@tabler/icons-react"
import { cn } from "@/registry/lib/utils"
import { ScrollFade } from "@/registry/ui/scroll-fade"
import {
Dialog,
DialogContent,
DialogDescription,
DialogHeader,
DialogTitle,
} from "@/registry/ui/dialog"
// @use-when a searchable palette of actions or destinations across the app,
// often opened with a shortcut. Not DropdownMenu, which lists one control's
// actions; not Combobox, which picks a value for a field; not SearchTrigger,
// which is only the header button that opens a palette.
function Command({
className,
...props
}: React.ComponentProps<typeof CommandPrimitive>) {
return (
<CommandPrimitive
data-slot="command"
className={cn(
"bg-popover text-popover-foreground flex h-full w-full flex-col overflow-hidden rounded-lg",
className
)}
{...props}
/>
)
}
// Which way a CommandDialog sits, read by CommandList for its default height.
const CommandDialogContext = React.createContext<{ position: "center" | "top" } | null>(null)
function CommandDialog({
title = "Command Palette",
description = "Search for a command to run…",
children,
className,
// Off by default: the dialog's close button sits in its top corner, and in
// a command dialog that corner is inside the search field, so the X read
// as a clear-search button. Esc, the footer's hint and a tap outside close it.
showCloseButton = false,
position = "center",
footer,
commandProps,
...props
}: Omit<React.ComponentProps<typeof Dialog>, "children"> & {
title?: string
description?: string
className?: string
showCloseButton?: boolean
/** `top` pins the window near the top of the viewport and lets it grow
* downward only, so a changing result count never moves the input. */
position?: "center" | "top"
/** A row under the list, for key hints. Hidden on touch, which has no keys. */
footer?: React.ReactNode
/** Passed to the inner Command: `shouldFilter={false}` for results that come
* from a server, `loop`, `filter`, a controlled `value`. */
commandProps?: Omit<React.ComponentProps<typeof Command>, "children">
children?: React.ReactNode
}) {
return (
<Dialog {...props}>
<DialogContent
data-position={position}
className={cn(
"overflow-hidden p-0",
// No vertical translate: the top edge is fixed and only the bottom
// moves. The height cap is whatever room is left under that edge.
position === "top" && "top-[12dvh] translate-y-0 origin-top max-h-[calc(88dvh-1rem)]",
className
)}
showCloseButton={showCloseButton}
>
<DialogHeader className="sr-only">
<DialogTitle>{title}</DialogTitle>
<DialogDescription>{description}</DialogDescription>
</DialogHeader>
<CommandDialogContext.Provider value={{ position }}>
{/* One content edge, 16px in from the popup: a row sits 8px in (its
group's px-2) and pads its label 8px more. The search field is a
box at the same 8px inset with the same 8px start padding, so its
icon lines up over the rows' labels, and it takes the rows'
rounded-md. No rule under it: the box is the field's edge. Rows
keep Command's own 32px menu rhythm. */}
<Command
{...commandProps}
className={cn(
"**:data-[slot=command-input-wrapper]:m-2 **:data-[slot=command-input-wrapper]:h-9 **:data-[slot=command-input-wrapper]:rounded-md **:data-[slot=command-input-wrapper]:border **:data-[slot=command-input-wrapper]:border-border **:data-[slot=command-input-wrapper]:bg-input-bg **:data-[slot=command-input-wrapper]:bg-clip-padding **:data-[slot=command-input-wrapper]:px-2 [&_[cmdk-input]]:h-full [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group]]:px-2 [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-3 [&_[cmdk-item]]:px-2",
commandProps?.className
)}
>
{children}
{footer && (
<div
data-slot="command-footer"
// gap-4 between hints: at least twice the 6px inside a hint
// (keys to word), so each hint reads as its own group. h-10
// leaves the hints the same air the search box has around it.
className="flex h-10 shrink-0 items-center gap-4 border-t border-border px-4 text-xs text-muted-foreground pointer-coarse:hidden"
>
{footer}
</div>
)}
</Command>
</CommandDialogContext.Provider>
</DialogContent>
</Dialog>
)
}
function CommandInput({
className,
...props
}: React.ComponentProps<typeof CommandPrimitive.Input>) {
return (
<div
data-slot="command-input-wrapper"
// No focus ring: this is the popup's one field and holds focus the whole
// time it is open, so the caret already marks it. A ring here drew a
// second edge inside the popup's own (rejected 2026-11-04).
className="flex h-10 items-center gap-2 border-b px-3"
>
<SearchIcon className="size-3.5 shrink-0 text-muted-foreground" />
<CommandPrimitive.Input
data-slot="command-input"
className={cn(
"placeholder:text-muted-foreground flex h-10 w-full bg-transparent py-3 text-field outline-hidden disabled:cursor-not-allowed disabled:opacity-70 md:text-sm",
className
)}
{...props}
/>
</div>
)
}
function CommandList({
className,
height,
...props
}: React.ComponentProps<typeof CommandPrimitive.List> & {
/** The list's height cap. `default` is 300px; `tall` is 40% of the viewport,
* for a palette with room under it. Inside a CommandDialog the list is
* always 40% of the viewport and fixed, not a cap: every search window in
* an app opens at one size and does not jump as results filter. */
height?: "default" | "tall"
}) {
const dialog = React.useContext(CommandDialogContext)
const cap = height ?? (dialog ? "tall" : "default")
// ScrollFade, not a hand-rolled edge mask. This used to carry its own copy of
// the skim logic plus `scrollbar-custom`, a class that lives in the SITE's
// globals.css and does not ship, so an installed Command showed a raw native
// scrollbar and a hard-cut bottom edge in every consumer project.
//
// Nesting a second scroller is safe here: cmdk keeps the selected item in
// view with `element.scrollIntoView({ block: "nearest" })`, which acts on
// whichever ancestor actually scrolls, so moving the overflow up one level to
// ScrollFade's viewport keeps arrow-key navigation working.
//
// The cap goes on the VIEWPORT, not the root: the viewport is `h-full`, and a
// percentage height against an auto-height parent resolves to auto, so a
// `max-h-*` on the root alone would leave the viewport as tall as its content
// and the root would clip it with nothing to scroll.
// scroll-pt-8: arrowing back up scrolls a group's first row into view, and
// without room above it the group's title stays hidden over the top.
return (
// ui-md-allow-arbitrary: `tall` is a share of the viewport, which the
// spacing scale cannot express; 40dvh keeps the whole window,
// input and footer included, near half the screen.
<ScrollFade
viewportClassName={cn(
// scroll-pb-6 is the fade's 24px: arrowing down stops a picked row
// above the bottom skim instead of under it.
"scroll-pt-8 scroll-pb-6",
// ui-md-allow-arbitrary: a share of the viewport, which the spacing scale cannot express
dialog ? "h-[40dvh]" : cap === "tall" ? "max-h-[40dvh]" : "max-h-75"
)}
>
<CommandPrimitive.List
data-slot="command-list"
className={cn(
// pb-2: the group only insets the last item 4px from the edge; add
// bottom breathing so the final row clears the modal corner (~12px,
// matching the item's horizontal text inset).
"scroll-py-1 overflow-x-hidden pb-2",
className
)}
{...props}
/>
</ScrollFade>
)
}
function CommandEmpty({
...props
}: React.ComponentProps<typeof CommandPrimitive.Empty>) {
return (
<CommandPrimitive.Empty
data-slot="command-empty"
className="py-6 text-center text-sm"
{...props}
/>
)
}
function CommandGroup({
className,
...props
}: React.ComponentProps<typeof CommandPrimitive.Group>) {
return (
<CommandPrimitive.Group
data-slot="command-group"
className={cn(
// A group title is a small caps label, not a quieter row: at the items'
// size it read as something to pick (Nav's group label, NavLabel, is the
// model). Select and DropdownMenu group labels share it.
"text-foreground overflow-hidden p-1 [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:pt-2 [&_[cmdk-group-heading]]:pb-1 [&_[cmdk-group-heading]]:text-2xs [&_[cmdk-group-heading]]:font-semibold [&_[cmdk-group-heading]]:tracking-wide [&_[cmdk-group-heading]]:uppercase [&_[cmdk-group-heading]]:text-muted-foreground",
className
)}
{...props}
/>
)
}
function CommandSeparator({
className,
...props
}: React.ComponentProps<typeof CommandPrimitive.Separator>) {
return (
<CommandPrimitive.Separator
data-slot="command-separator"
// No line before a titled group: the small caps title and the space
// above it already mark the break, as most command palettes do, and a
// rule on top of a title is two separators for one break. A separator
// still draws between untitled groups, which have nothing else.
className={cn(
"bg-border -mx-1 h-px [&:has(+[data-slot=command-group]_[cmdk-group-heading])]:hidden",
className
)}
{...props}
/>
)
}
function CommandItem({
className,
...props
}: React.ComponentProps<typeof CommandPrimitive.Item>) {
// The highlight is a soft neutral fill under foreground text, the way a
// palette or menu shows where the keyboard is. It is not a selection, so it
// does not take the accent tint.
return (
<CommandPrimitive.Item
data-slot="command-item"
className={cn(
"group/command-item data-[selected=true]:bg-secondary data-[selected=true]:text-foreground data-[selected=true]:[&_svg:not([class*='text-'])]:text-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex cursor-pointer items-center gap-2 rounded-md px-2 py-1.5 pointer-coarse:py-3 text-sm outline-hidden select-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3",
className
)}
{...props}
/>
)
}
function CommandShortcut({
className,
...props
}: React.ComponentProps<"span">) {
return (
<span
data-slot="command-shortcut"
className={cn(
// Brightens with the row: a highlighted row's label goes to
// foreground, and a hint left muted beside it reads as disabled.
"text-muted-foreground group-data-[selected=true]/command-item:text-foreground ms-auto text-xs tracking-widest",
className
)}
{...props}
/>
)
}
// A small square image at the start of a row: a cover, a logo, a favicon.
//
// Size: 20px, the largest 4px step inside the label's line box (14px at 1.5 is
// 21px), so a row with media is exactly as tall as a row without. It is also
// the icon box CommandDialog sets, so a palette mixing icons and covers keeps
// one column. Avatar's smallest rung (24px) would add 3px to every media row.
//
// Radius: nesting beats the tier. The row is `rounded-md` (8px) inset by its
// own `px-2` (8px), so parent minus inset is 0; at 0 or below the child takes
// the ladder's first rung, `rounded-xs` (4px), instead of a square corner.
//
// Gap: the row's own 8px, the same as an icon. The `media` rung (16px) is for a
// pairing that stands alone; inside a row inset 8px, a 16px gap would sit the
// image closer to the row's edge than to the label it names.
//
// The muted fill holds the square while the image loads or when there is none,
// and the hairline is the kit's image outline. Decorative by default (`alt=""`),
// since the row's label already names it. Pass `src`, or your own image element
// as children (a framework image with `fill` works: the box is `relative`).
function CommandItemMedia({
src,
alt = "",
className,
children,
...props
}: React.ComponentProps<"span"> & {
src?: string
alt?: string
}) {
return (
<span
data-slot="command-item-media"
className={cn(
"relative size-5 shrink-0 overflow-hidden rounded-xs bg-muted *:size-full *:object-cover after:pointer-events-none after:absolute after:inset-0 after:rounded-xs after:ring-1 after:ring-inset after:ring-black/10 dark:after:ring-white/10",
className
)}
{...props}
>
{children ??
(src ? (
// The kit is framework-agnostic; on Next, pass next/image as children.
// eslint-disable-next-line @next/next/no-img-element
<img src={src} alt={alt} />
) : null)}
</span>
)
}
// Words at the end of a row: a topic, a type, a count. CommandShortcut is for
// key glyphs and spaces them apart; words need ordinary tracking. One type step
// below the label, muted, and brightened with the row like the label.
function CommandItemMeta({
className,
...props
}: React.ComponentProps<"span">) {
return (
<span
data-slot="command-item-meta"
className={cn(
"text-muted-foreground group-data-[selected=true]/command-item:text-foreground ms-auto shrink-0 text-xs",
className
)}
{...props}
/>
)
}
export {
Command,
CommandDialog,
CommandInput,
CommandList,
CommandEmpty,
CommandGroup,
CommandItem,
CommandItemMedia,
CommandItemMeta,
CommandShortcut,
CommandSeparator,
}