Command
A command palette for searching and executing actions. Built on cmdk.
Installation
$
Usage
import { Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut } from "@/components/ui/command"Examples
Default
Dialog (⌘K)
The modal command palette. CommandDialog wires the title and description for accessibility; bind ⌘K to toggle it.
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. |
| shouldFilterCommand | boolean | true | Whether cmdk filters and ranks items against the search query. Set false to filter results yourself. |
| filterCommand | (value, search, keywords) => number | - | 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. |
| headingCommandGroup | React.ReactNode | - | Label rendered above the group's items. |
| valueCommandItem | string | - | Explicit value used for filtering and selection; defaults to the item's text content. |
| onSelectCommandItem | (value: string) => void | - | Called when the item is chosen via click or Enter. |
| disabledCommandItem | boolean | false | Disables the item so it can't be selected. |
"use client"
import * as React from "react"
import { Command as CommandPrimitive } from "cmdk"
import { SearchIcon } from "lucide-react"
import { cn } from "@/registry/lib/utils"
import {
Dialog,
DialogContent,
DialogDescription,
DialogHeader,
DialogTitle,
} from "@/registry/ui/dialog"
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}
/>
)
}
function CommandDialog({
title = "Command Palette",
description = "Search for a command to run...",
children,
className,
showCloseButton = true,
...props
}: Omit<React.ComponentProps<typeof Dialog>, "children"> & {
title?: string
description?: string
className?: string
showCloseButton?: boolean
children?: React.ReactNode
}) {
return (
<Dialog {...props}>
<DialogContent
className={cn("overflow-hidden p-0", className)}
showCloseButton={showCloseButton}
>
<DialogHeader className="sr-only">
<DialogTitle>{title}</DialogTitle>
<DialogDescription>{description}</DialogDescription>
</DialogHeader>
<Command className="[&_[cmdk-group-heading]]:text-muted-foreground **:data-[slot=command-input-wrapper]:h-12 [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group]]:px-2 [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5">
{children}
</Command>
</DialogContent>
</Dialog>
)
}
function CommandInput({
className,
...props
}: React.ComponentProps<typeof CommandPrimitive.Input>) {
return (
<div
data-slot="command-input-wrapper"
className="flex h-10 items-center gap-2 border-b px-3"
>
<SearchIcon className="size-4 shrink-0 opacity-50" />
<CommandPrimitive.Input
data-slot="command-input"
className={cn(
"placeholder:text-muted-foreground flex h-10 w-full bg-transparent py-3 text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50",
className
)}
{...props}
/>
</div>
)
}
function CommandList({
className,
...props
}: React.ComponentProps<typeof CommandPrimitive.List>) {
const ref = React.useRef<HTMLDivElement>(null)
// Edge skim that ramps in with scroll distance (same technique as ScrollFade)
// applied straight to cmdk's own scroll element - it manages scrolling the
// selected item into view, so we enhance it in place rather than nesting a
// second scroller. The mask fades content (and the scrollbar's ends) into the
// popover surface. cmdk filters items live, so we also observe its inner
// sizer; otherwise the fade goes stale as results change.
React.useEffect(() => {
const el = ref.current
if (!el) return
function update() {
if (!el) return
const top = Math.min(el.scrollTop, 20)
const bottom = Math.min(el.scrollHeight - el.clientHeight - el.scrollTop, 20)
el.style.setProperty("--sf-top", `${Math.max(top, 0)}px`)
el.style.setProperty("--sf-bottom", `${Math.max(bottom, 0)}px`)
}
update()
el.addEventListener("scroll", update, { passive: true })
const observer = new ResizeObserver(update)
observer.observe(el)
const sizer = el.querySelector("[cmdk-list-sizer]")
if (sizer) observer.observe(sizer)
return () => {
el.removeEventListener("scroll", update)
observer.disconnect()
}
}, [])
// Layer 1 fades the top/bottom edges; layer 2 keeps the right gutter (the 6px
// scrollbar lane) opaque so the bar stays crisp. mask-composite unions them.
const fade =
"linear-gradient(to bottom, transparent 0, #000 var(--sf-top, 0px), #000 calc(100% - var(--sf-bottom, 0px)), transparent 100%)"
const keepScrollbar = "linear-gradient(to left, #000 6px, transparent 6px)"
const image = `${fade}, ${keepScrollbar}`
const maskStyle: React.CSSProperties = {
maskImage: image,
WebkitMaskImage: image,
maskComposite: "add",
WebkitMaskComposite: "source-over",
maskRepeat: "no-repeat",
WebkitMaskRepeat: "no-repeat",
}
return (
<CommandPrimitive.List
ref={ref}
data-slot="command-list"
style={maskStyle}
className={cn(
// scrollbar-custom: the kit's shared thin scrollbar (app/globals.css).
// 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).
"scrollbar-custom max-h-75 scroll-py-1 overflow-x-hidden overflow-y-auto pb-2",
className
)}
{...props}
/>
)
}
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(
"text-foreground [&_[cmdk-group-heading]]:text-muted-foreground overflow-hidden p-1 [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium",
className
)}
{...props}
/>
)
}
function CommandSeparator({
className,
...props
}: React.ComponentProps<typeof CommandPrimitive.Separator>) {
return (
<CommandPrimitive.Separator
data-slot="command-separator"
className={cn("bg-border -mx-1 h-px", className)}
{...props}
/>
)
}
function CommandItem({
className,
...props
}: React.ComponentProps<typeof CommandPrimitive.Item>) {
return (
<CommandPrimitive.Item
data-slot="command-item"
className={cn(
"data-[selected=true]:bg-accent-100 dark:data-[selected=true]:bg-accent-900 data-[selected=true]:text-accent data-[selected=true]:[&_svg:not([class*='text-'])]:text-accent [&_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(
"text-muted-foreground ml-auto text-xs tracking-widest",
className
)}
{...props}
/>
)
}
export {
Command,
CommandDialog,
CommandInput,
CommandList,
CommandEmpty,
CommandGroup,
CommandItem,
CommandShortcut,
CommandSeparator,
}