Ballmac UI home

Command

A filterable command list on cmdk, inline or in a Cmd/Ctrl+K dialog, with groups, shortcuts, descriptions, loading state and page-safe scrolling.

Installation

$ pnpm dlx shadcn@latest add @ballmac/command

Usage

import { Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandLoading, CommandGroup, CommandItem, CommandShortcut, CommandSeparator } from "@/components/ballmac/command"

The full example is in the Code tab above.

Examples

Cmd+K dialog

Last command: Nothing run yet

API reference

<CommandDialog>

PropTypeDefault
open

Controlled open state.

boolean—
defaultOpen

Initial open state when uncontrolled.

booleanfalse
onOpenChange

Called when the dialog opens or closes.

(open: boolean) => void—
hotkey

Key that toggles the dialog together with ⌘ (Ctrl on Windows and Linux). `false` turns the shortcut off.

string | false"k"
title

Accessible title of the dialog (visually hidden).

string—
description

Accessible description of the dialog (visually hidden).

string—

<CommandItem>

PropTypeDefault
icon

Leading icon. Use this instead of putting the icon in `children` when the item has a `description`.

React.ReactNode—
description

Second line of muted text under the title.

React.ReactNode—
selected

Show a check at the end, for the currently chosen option in a picker.

boolean—

Also accepts the standard attributes of its root element.

Accessibility

KeyAction
TypeFilters the list
ArrowUp / ArrowDownMoves the highlighted item
EnterRuns the highlighted item
Cmd/Ctrl+KToggles CommandDialog
EscapeCloses the dialog

Use with AI

Compose Command, CommandInput, CommandList, CommandGroup and CommandItem. CommandDialog adds the modal and the ⌘K hotkey. With the shadcn MCP server set up (guide), ask your agent:

Add the Ballmac UI Command (@ballmac/command) to this project with the shadcn MCP, then use it where it fits.

Use it for

  • Command palettes and quick switchers
  • Searchable action lists
  • The list inside a combobox

Not for

  • macOS-style launcher visuals; use spotlight-search
  • A simple select; use select

Registry JSON: https://ui.ballmac.com/r/command.json

Credits

Based on shadcn/ui Command, adapted by Ballmac. Free to use in personal and commercial projects.