Skip to the content

Controls and surfaces

command

A command palette: a search field over a filtered, keyboard-driven list of actions, inline or in a dialog.

Overlays and navigation

When to use it

Fast access to many actions or pages by typing (the Ctrl/Cmd+K palette), or a searchable list inside a popover. For a handful of actions use dropdown-menu. CommandDialog is usually opened by a shortcut, with no trigger, so focus has nowhere to return: remember the opener (opener.current = document.activeElement before opening) and refocus it in onCloseAutoFocus={(event) => { event.preventDefault(); opener.current?.focus(); }}.

See it working

The demonstration the browser checks drive, with the keyboard as well as the pointer. More of it is on the Overlays and navigation page.

Dialog, sheet, popover, tooltip, toast

Dropdown and context menu

Right-click or long-press here

Tabs

The underline look, for sections of a page.

Accordion

Yes. Components are copied into your project.

Breadcrumb and pagination

Add it

npx shadcn@latest add @rivier-ui/command

The registry is named once in components.json: see Installation.

Example

Import it from @/components/ui/command.

const [open, setOpen] = useState(false);

<Button variant="outline" onClick={() => setOpen(true)}>Search</Button>
<CommandDialog open={open} onOpenChange={setOpen}>
  <CommandInput placeholder="Type a command" />
  <CommandList>
    <CommandEmpty>Nothing found.</CommandEmpty>
    <CommandGroup heading="Pages">
      <CommandItem onSelect={() => setOpen(false)}>Dashboard</CommandItem>
      <CommandItem onSelect={() => setOpen(false)}>Settings <CommandShortcut>Ctrl ,</CommandShortcut></CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup heading="Account">
      <CommandItem onSelect={() => setOpen(false)}>Sign out</CommandItem>
    </CommandGroup>
  </CommandList>
</CommandDialog>

What it needs

A client component: it uses state, effects or browser behaviour. Packages: cmdk, lucide-react.

It imports

It is used by

Source

The whole file. Once copied it is yours: the registry item holds the same text.

src/components/ui/command.tsx
"use client";
/**
 * @name command
 * @category ui
 * @description A command palette: a search field over a filtered, keyboard-driven list of actions, inline or in a dialog.
 * @when Fast access to many actions or pages by typing (the Ctrl/Cmd+K palette), or a searchable list inside a popover. For a handful of actions use dropdown-menu. CommandDialog is usually opened by a shortcut, with no trigger, so focus has nowhere to return: remember the opener (`opener.current = document.activeElement` before opening) and refocus it in `onCloseAutoFocus={(event) => { event.preventDefault(); opener.current?.focus(); }}`.
 * @example
 * const [open, setOpen] = useState(false);
 *
 * <Button variant="outline" onClick={() => setOpen(true)}>Search</Button>
 * <CommandDialog open={open} onOpenChange={setOpen}>
 *   <CommandInput placeholder="Type a command" />
 *   <CommandList>
 *     <CommandEmpty>Nothing found.</CommandEmpty>
 *     <CommandGroup heading="Pages">
 *       <CommandItem onSelect={() => setOpen(false)}>Dashboard</CommandItem>
 *       <CommandItem onSelect={() => setOpen(false)}>Settings <CommandShortcut>Ctrl ,</CommandShortcut></CommandItem>
 *     </CommandGroup>
 *     <CommandSeparator />
 *     <CommandGroup heading="Account">
 *       <CommandItem onSelect={() => setOpen(false)}>Sign out</CommandItem>
 *     </CommandGroup>
 *   </CommandList>
 * </CommandDialog>
 */
import { Command as CommandPrimitive } from "cmdk";
import { Search } from "lucide-react";
import type { ComponentProps } from "react";
import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, type DialogContentProps } from "@/components/ui/dialog";
import { cn } from "@/lib/cn";

/** The palette itself. Use it inline (in a card or popover), or let CommandDialog wrap it. */
export function Command({ className, ...props }: ComponentProps<typeof CommandPrimitive>) {
  return (
    <CommandPrimitive
      data-slot="command"
      className={cn("flex min-h-0 w-full flex-col overflow-hidden rounded-surface bg-popover text-popover-foreground", className)}
      {...props}
    />
  );
}

export type CommandDialogProps = ComponentProps<typeof Dialog> &
  Pick<DialogContentProps, "onCloseAutoFocus" | "onOpenAutoFocus"> & {
    /** The dialog's accessible name. Read by screen readers, not shown. */
    title?: string;
    /** The dialog's accessible description. Read by screen readers, not shown. */
    description?: string;
    /** Classes for the dialog window. */
    className?: string;
    /** Props for the palette inside: `filter`, `shouldFilter`, `loop`, `label`. */
    commandProps?: ComponentProps<typeof CommandPrimitive>;
  };

/** The palette in a dialog. Escape and a click outside close it, so it has no close button. */
export function CommandDialog({
  title = "Command palette",
  description = "Type to search, use the arrow keys to move, Enter to run.",
  className,
  commandProps,
  onCloseAutoFocus,
  onOpenAutoFocus,
  children,
  ...props
}: CommandDialogProps) {
  return (
    <Dialog {...props}>
      <DialogContent
        showCloseButton={false}
        onCloseAutoFocus={onCloseAutoFocus}
        onOpenAutoFocus={onOpenAutoFocus}
        className={cn("gap-0 overflow-hidden bg-popover p-0 text-popover-foreground", className)}
      >
        <DialogHeader className="sr-only">
          <DialogTitle>{title}</DialogTitle>
          <DialogDescription>{description}</DialogDescription>
        </DialogHeader>
        <Command {...commandProps}>{children}</Command>
      </DialogContent>
    </Dialog>
  );
}

/** The search field. The focus ring is drawn on the whole row, inside its edge. */
export function CommandInput({ className, ...props }: ComponentProps<typeof CommandPrimitive.Input>) {
  return (
    <div
      data-slot="command-input-wrapper"
      className="flex h-12 shrink-0 items-center gap-2 border-b px-3.5 has-focus-visible:outline-2 has-focus-visible:-outline-offset-2 has-focus-visible:outline-ring"
    >
      <Search aria-hidden="true" strokeWidth={1.5} className="size-4 shrink-0 text-muted-foreground" />
      <CommandPrimitive.Input
        data-slot="command-input"
        className={cn(
          "h-full min-w-0 flex-1 bg-transparent text-base outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
          className,
        )}
        {...props}
      />
    </div>
  );
}

export function CommandList({ className, ...props }: ComponentProps<typeof CommandPrimitive.List>) {
  return (
    <CommandPrimitive.List
      data-slot="command-list"
      className={cn("max-h-80 min-h-0 scroll-py-1 overflow-x-hidden overflow-y-auto p-1", className)}
      {...props}
    />
  );
}

export function CommandEmpty({ className, ...props }: ComponentProps<typeof CommandPrimitive.Empty>) {
  return <CommandPrimitive.Empty data-slot="command-empty" className={cn("px-2.5 py-6 text-center text-sm text-muted-foreground", className)} {...props} />;
}

export function CommandGroup({ className, ...props }: ComponentProps<typeof CommandPrimitive.Group>) {
  return (
    <CommandPrimitive.Group
      data-slot="command-group"
      className={cn(
        "overflow-hidden text-foreground [&_[cmdk-group-heading]]:px-2.5 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground",
        className,
      )}
      {...props}
    />
  );
}

export function CommandSeparator({ className, ...props }: ComponentProps<typeof CommandPrimitive.Separator>) {
  return <CommandPrimitive.Separator data-slot="command-separator" className={cn("-mx-1 my-1 h-px bg-border", className)} {...props} />;
}

/** One action. Focus stays in the search field; the active item is marked by cmdk's `data-selected`. */
export function CommandItem({ className, ...props }: ComponentProps<typeof CommandPrimitive.Item>) {
  return (
    <CommandPrimitive.Item
      data-slot="command-item"
      className={cn(
        "relative flex min-h-9 cursor-default items-center gap-2 rounded-control px-2.5 py-1.5 text-sm select-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground pointer-coarse:min-h-10 [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
        className,
      )}
      {...props}
    />
  );
}

/** A keyboard hint at the end of an item. It only shows the keys: bind them yourself. */
export function CommandShortcut({ className, ...props }: ComponentProps<"span">) {
  return <span data-slot="command-shortcut" className={cn("ms-auto ps-4 text-xs tracking-widest text-muted-foreground", className)} {...props} />;
}