UI

Command palette

A searchable command surface with grouped results and keyboard control.

Read Markdown

Web 0.2.0

  • Defaultlight16.03 : 1AA 4.5dark4.90 : 1AA 4.5
  • KeyboardEnterArrowDownArrowUpTabShift+TabEscape
  • measured on 0.2.0
npx shadcn@latest add @maeso/command-palette
Size
62.3 kB gzipmeasured on 0.2.0

Usage

Supply named commands and execute the selected command in the parent. Make the empty search result actionable.

Accessibility

Label the search and preserve active-result navigation, Enter activation and Escape dismissal. Keep focus restoration on close.

When to use

Use for fast command discovery across an application. Keep essential actions available through ordinary navigation too.

Install

Add this registry to your project's components.json once, before the first install. Keep your existing settings and other registries.

{
  "registries": {
    "@maeso": "http://127.0.0.1:4321/r/{name}.json"
  }
}

Then install the registry's default theme once, and import its sheet in the CSS entry that imports Tailwind. It paints every item from this registry.

npx shadcn@latest add @maeso/maeso
@import "./styles/theme.web.css";
npx shadcn@latest add @maeso/command-palette

Props

CommandPalette

PropTypeRequiredDescription
commandsreadonly Command[] | undefinedno
containedboolean | undefinedno
emptyLabelstring | undefinedno
footerReactNodenoPass `null` to drop the hint bar entirely.
initialQuerystring | undefinednoWhat the field already holds when the palette opens: a query a capture reaches untyped.
onClose(() => void) | undefinedno
openboolean | undefinedno
openShortcutstring | undefinednoThe chord that opens the palette, shown at the hint bar's end as "Search anywhere".
placeholderstring | undefinedno
search((query: string) => readonly Command[]) | undefinednoThe rows for one query, where the caller searches more than labels. Given, it replaces the palette's own filter and `commands` is ignored.
styleCSSProperties | undefinedno

Proof

Contrast

measured on 0.2.0

StateForegroundBackgroundRatioFloor
defaultrgb(7 21 34)rgb(239 239 239)16.03AA 4.5
default (dark)rgb(248 245 240)rgb(107 107 107)4.90AA 4.5

Keyboard

measured on 0.2.0

KeyAction
EnterOpen the palette or run the active command and return focus
ArrowDownMove the active command down
ArrowUpMove the active command up
TabKeep forward focus in the palette
Shift+TabKeep backward focus in the palette
EscapeDismiss without another command and restore focus

Size

62268 gzip bytes · measured on 0.2.0

Motion

The scrim fades and the command panel enters above it.

Configured duration: 200 ms

Reduced motion: none

Motion timing

Observed duration: 200 ms · measured on 0.2.0

Reduced motion

passed · measured on 0.2.0

Example

import { CommandPalette } from "@/components/ui/_kit/overlay/command-palette/CommandPalette";
import { useState } from "react";

export default function Example() {
const [open, setOpen] = useState(false);
return <><button onClick={() => setOpen(true)}>Open commands</button><CommandPalette open={open} onClose={() => setOpen(false)} commands={[{ id: "new", label: "New document", icon: "file-plus" }]} /></>;
}

not on native yet