Add this component

npx zentauri-ui add command

Accessibility notes

Overlay patterns include focus, dismissal, and semantic roles where the component owns interaction. Verify trigger labels and escape behavior in your flow.

Dependency notes

Static imports do not pull framer-motion. Use the animated entry only when you want motion and have framer-motion installed.

Overlay

Command palette for fast navigation

A command palette gives people a keyboard-first way to search and run actions from anywhere in an app. Zentauri UI ships a composable Command primitive with a global Cmd+K hotkey, grouped results, live filtering, an empty state, and an optional animated entry — themeable through --zui-command-* tokens.

Examples

Use the animated entrypoint when the palette should spring in. It honors reduced-motion preferences and falls back to a fade.

Command palette variants playground

Pick an appearance and size to preview the command palette live. Toggle Show output / Show code and the snippet updates to match the selected variant.

Appearance

Size

All appearances

Every shipped appearance token at a glance. Click any swatch to load it into the playground above.

Search default

Open command

Create project

Search glass

Open command

Create project

Search sky

Open command

Create project

Search rose

Open command

Create project

Search purple

Open command

Create project

Search pink

Open command

Create project

Search orange

Open command

Create project

Search yellow

Open command

Create project

Search teal

Open command

Create project

Search indigo

Open command

Create project

Search emerald

Open command

Create project

Search gray

Open command

Create project

Search amber

Open command

Create project

Search violet

Open command

Create project

Search gradient-blue

Open command

Create project

Search gradient-green

Open command

Create project

Search gradient-red

Open command

Create project

Search gradient-yellow

Open command

Create project

Search gradient-purple

Open command

Create project

Search gradient-teal

Open command

Create project

Search gradient-indigo

Open command

Create project

Search gradient-pink

Open command

Create project

Search blue

Open command

Create project

Search cyan

Open command

Create project

Search green

Open command

Create project

Search lime

Open command

Create project

Search mint

Open command

Create project

Search ocean

Open command

Create project

Search sapphire

Open command

Create project

Search lavender

Open command

Create project

Search ruby

Open command

Create project

Search red

Open command

Create project

Search slate

Open command

Create project

Search zinc

Open command

Create project

Search stone

Open command

Create project

Search royal

Open command

Create project

Search electric

Open command

Create project

Search forest

Open command

Create project

Search sunset

Open command

Create project

Search magenta

Open command

Create project

Search crimson

Open command

Create project

Search aqua

Open command

Create project

Search plum

Open command

Create project

Hotkey: ⌘K / Ctrl+K — open the palette from anywhere without a trigger button.

Command API

Generated from the package prop types and variant definitions.

Command

CommandProps

State

Prop	Type	Default
defaultOpen	`boolean \| undefined`	none
onOpenChange	`((open: boolean) => void) \| undefined`	none
open	`boolean \| undefined`	none

Behavior

Prop	Type	Default
hotkeyWhen set, binds a global shortcut that toggles the palette: this key plus meta (⌘) or ctrl. Defaults to "k" when `hotkey` is `true`.	`string \| boolean \| undefined`	none
labelAccessible label for the dialog.	`string \| undefined`	none

Content

Prop	Type	Default
children	`ReactNode`	none

CommandContent

CommandContentProps

Variants

Prop	Type	Default
appearance	`amberaquabluecrimsoncyandefaultelectricemeraldforestglassgradient-bluegradient-green`+31	default
size	`lgmdsm`	md

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none
id	`string \| undefined`	none
style	`CSSProperties \| undefined`	none

CommandContentLayer

CommandContentLayerProps

Behavior

Prop	Type	Default
appearance	'default' \| 'blue' \| 'cyan' \| 'green' \| 'lime' \| 'mint' \| 'ocean' \| 'sapphire' \| 'lavender' \| 'ruby' \| 'red' \| 'slate' \| 'zinc' \| 'stone' \| 'royal' \| 'electric' \| 'forest' \| 'sunset' \| 'magenta' \| 'crimson' \| 'aqua' \| 'plum' \| 'sky' \| 'rose' \| 'purple' \| 'pink' \| 'orange' \| 'yellow' \| 'teal' \| 'indigo' \| 'emerald' \| 'gradient-blue' \| 'gradient-green' \| 'gradient-red' \| 'gradient-yellow' \| 'gradient-purple' \| 'gradient-teal' \| 'gradient-indigo' \| 'gradient-pink' \| 'gray' \| 'violet' \| 'glass' \| 'amber' \| null \| undefined	none
componentName*	`string`	none
renderOverlay	`((props: CommandContentOverlayRenderProps) => ReactNode) \| undefined`	none
renderPanel	`((props: CommandContentPanelRenderProps) => ReactNode) \| undefined`	none
renderPresence	`((children: ReactNode) => ReactNode) \| undefined`	none
size	`'md' \| 'sm' \| 'lg' \| null \| undefined`	none

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none
id	`string \| undefined`	none
style	`CSSProperties \| undefined`	none

CommandContentOverlayRender

CommandContentOverlayRenderProps

Behavior

Prop	Type	Default
onClick*	`() => void`	none
role*	`'presentation'`	none

Inherited HTML props

Prop	Type	Default
className*	`string`	none

CommandContentPanelRender

CommandContentPanelRenderProps

Behavior

Prop	Type	Default
role*	`'dialog'`	none
tabIndex*	`-1`	none

Content

Prop	Type	Default
children*	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className*	`string`	none
id	`string \| undefined`	none
style	`CSSProperties \| undefined`	none

CommandContentVariant

CommandContentVariantProps

Behavior

Prop	Type	Default
appearance	'default' \| 'blue' \| 'cyan' \| 'green' \| 'lime' \| 'mint' \| 'ocean' \| 'sapphire' \| 'lavender' \| 'ruby' \| 'red' \| 'slate' \| 'zinc' \| 'stone' \| 'royal' \| 'electric' \| 'forest' \| 'sunset' \| 'magenta' \| 'crimson' \| 'aqua' \| 'plum' \| 'sky' \| 'rose' \| 'purple' \| 'pink' \| 'orange' \| 'yellow' \| 'teal' \| 'indigo' \| 'emerald' \| 'gradient-blue' \| 'gradient-green' \| 'gradient-red' \| 'gradient-yellow' \| 'gradient-purple' \| 'gradient-teal' \| 'gradient-indigo' \| 'gradient-pink' \| 'gray' \| 'violet' \| 'glass' \| 'amber' \| null \| undefined	none
size	`'md' \| 'sm' \| 'lg' \| null \| undefined`	none

CommandGroup

CommandGroupProps

Behavior

Prop	Type	Default
heading	`ReactNode`	none

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none

CommandInput

CommandInputProps

Behavior

Prop	Type	Default
placeholder	`string \| undefined`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none

CommandItem

CommandItemProps

State

Prop	Type	Default
value*Stable identifier used for filtering, keyboard nav, and onSelect.	`string`	none

Behavior

Prop	Type	Default
disabled	`boolean \| undefined`	none
keywordsExtra terms used by the filter in addition to the rendered text.	`string[] \| undefined`	none
onSelect	`((value: string) => void) \| undefined`	none

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none

CommandList

CommandListProps

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none

CommandTrigger

CommandTriggerProps

Behavior

Prop	Type	Default
onClick	`((event: React.MouseEvent<HTMLButtonElement>) => void) \| undefined`	none

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none

CommandContentAnimated

CommandContentAnimatedProps

animated

Behavior

Prop	Type	Default
animation	`CommandAnimation \| undefined`	none
appearance	'default' \| 'blue' \| 'cyan' \| 'green' \| 'lime' \| 'mint' \| 'ocean' \| 'sapphire' \| 'lavender' \| 'ruby' \| 'red' \| 'slate' \| 'zinc' \| 'stone' \| 'royal' \| 'electric' \| 'forest' \| 'sunset' \| 'magenta' \| 'crimson' \| 'aqua' \| 'plum' \| 'sky' \| 'rose' \| 'purple' \| 'pink' \| 'orange' \| 'yellow' \| 'teal' \| 'indigo' \| 'emerald' \| 'gradient-blue' \| 'gradient-green' \| 'gradient-red' \| 'gradient-yellow' \| 'gradient-purple' \| 'gradient-teal' \| 'gradient-indigo' \| 'gradient-pink' \| 'gray' \| 'violet' \| 'glass' \| 'amber' \| null \| undefined	none
size	`'md' \| 'sm' \| 'lg' \| null \| undefined`	none

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none
id	`string \| undefined`	none
style	`CSSProperties \| undefined`	none

CSS variable overrides

Command CSS variables

Override these command palette variables on :root, a theme selector, or a component wrapper to tune the overlay, trigger, panel, input, items, and appearance variants.

224 variables

Pattern: --zui-<component>-<slot?>-<variant?>-<property>-<state?>-dark?

:root {
  --zui-command-overlay-bg: oklch(12.9% 0.042 264.695 / 0.6);
  --zui-command-trigger-border: #0000001a;
  --zui-command-trigger-bg: oklch(98.4% 0.003 247.858);
  --zui-command-trigger-fg: oklch(44.6% 0.03 256.802);
  --zui-command-content-border: #0000001a;
  --zui-command-content-bg: oklch(98.4% 0.003 247.858);
  --zui-command-content-fg: oklch(20.8% 0.042 265.755);
  --zui-command-content-shadow: 0 12px 40px rgba(15,23,42,0.18);
  --zui-command-input-border: #0000000f;
  --zui-command-input-fg: oklch(20.8% 0.042 265.755);
  --zui-command-input-placeholder: oklch(55.1% 0.027 264.364);
  --zui-command-group-heading-fg: oklch(55.1% 0.027 264.364);
  --zui-command-item-fg: oklch(27.8% 0.033 256.848);
  --zui-command-item-active-bg: oklch(95.1% 0.026 236.824);
  --zui-command-item-active-fg: oklch(20.8% 0.042 265.755);
  --zui-command-separator-bg: #0000000f;
  --zui-command-empty-fg: oklch(55.1% 0.027 264.364);
  --zui-command-footer-border: #0000000f;
  --zui-command-footer-fg: oklch(55.1% 0.027 264.364);
  --zui-command-content-default-bg: oklch(98.4% 0.003 247.858);
  --zui-command-content-glass-border: #00000026;
  --zui-command-content-glass-bg: oklch(98.4% 0.003 247.858 / 0.7);
  --zui-command-content-sky-border: oklch(44.3% 0.11 240.79);
  --zui-command-content-sky-bg: oklch(97.7% 0.013 236.62);
  --zui-command-content-rose-border: oklch(45.5% 0.188 13.697);
  --zui-command-content-rose-bg: oklch(96.9% 0.015 12.422);
  --zui-command-content-purple-border: oklch(43.8% 0.218 303.724);
  --zui-command-content-purple-bg: oklch(97.7% 0.014 308.299);
  --zui-command-content-pink-border: oklch(45.9% 0.187 3.815);
  --zui-command-content-pink-bg: oklch(97.1% 0.014 343.198);
  --zui-command-content-orange-border: oklch(47% 0.157 37.304);
  --zui-command-content-orange-bg: oklch(98% 0.016 73.684);
  --zui-command-content-yellow-border: oklch(47.6% 0.114 61.907);
  --zui-command-content-yellow-bg: oklch(98.7% 0.026 102.212);
  --zui-command-content-teal-border: oklch(43.7% 0.078 188.216);
  --zui-command-content-teal-bg: oklch(98.4% 0.014 180.72);
  --zui-command-content-indigo-border: oklch(39.8% 0.195 277.366);
  --zui-command-content-indigo-bg: oklch(96.2% 0.018 272.314);
  --zui-command-content-emerald-border: oklch(43.2% 0.095 166.913);
  --zui-command-content-emerald-bg: oklch(97.9% 0.021 166.113);
  --zui-command-content-gray-border: oklch(27.8% 0.033 256.848);
  --zui-command-content-gray-bg: oklch(98.5% 0.002 247.839);
  --zui-command-content-amber-border: oklch(47.3% 0.137 46.201);
  --zui-command-content-amber-bg: oklch(98.7% 0.022 95.277);
  --zui-command-content-violet-border: oklch(43.2% 0.232 292.759);
  --zui-command-content-violet-bg: oklch(96.9% 0.016 293.756);
  --zui-command-content-gradient-blue-border: oklch(42.4% 0.199 265.638);
  --zui-command-content-gradient-blue-from: oklch(97% 0.014 254.604);
  --zui-command-content-gradient-blue-to: oklch(97.7% 0.014 308.299);
  --zui-command-content-gradient-green-border: oklch(44.8% 0.119 151.328);
  --zui-command-content-gradient-green-from: oklch(98.2% 0.018 155.826);
  --zui-command-content-gradient-green-to: oklch(98.6% 0.031 120.757);
  --zui-command-content-gradient-red-border: oklch(44.4% 0.177 26.899);
  --zui-command-content-gradient-red-from: oklch(97.1% 0.013 17.38);
  --zui-command-content-gradient-red-to: oklch(97.1% 0.014 343.198);
  --zui-command-content-gradient-yellow-border: oklch(47.6% 0.114 61.907);
  --zui-command-content-gradient-yellow-from: oklch(98.7% 0.026 102.212);
  --zui-command-content-gradient-yellow-to: oklch(98% 0.016 73.684);
  --zui-command-content-gradient-purple-border: oklch(43.8% 0.218 303.724);
  --zui-command-content-gradient-purple-from: oklch(97.7% 0.014 308.299);
  --zui-command-content-gradient-purple-to: oklch(97.1% 0.014 343.198);
  --zui-command-content-gradient-teal-border: oklch(43.7% 0.078 188.216);
  --zui-command-content-gradient-teal-from: oklch(98.4% 0.014 180.72);
  --zui-command-content-gradient-teal-to: oklch(98.4% 0.019 200.873);
  --zui-command-content-gradient-indigo-border: oklch(39.8% 0.195 277.366);
  --zui-command-content-gradient-indigo-from: oklch(96.2% 0.018 272.314);
  --zui-command-content-gradient-indigo-to: oklch(97.7% 0.014 308.299);
  --zui-command-content-gradient-pink-border: oklch(45.9% 0.187 3.815);
  --zui-command-content-gradient-pink-from: oklch(97.1% 0.014 343.198);
  --zui-command-content-gradient-pink-to: oklch(96.9% 0.015 12.422);
  --zui-command-content-blue-border: #2563eb;
  --zui-command-content-blue-bg: #2563eb14;
  --zui-command-content-cyan-border: #0891b2;
  --zui-command-content-cyan-bg: #0891b214;
  --zui-command-content-green-border: #16a34a;
  --zui-command-content-green-bg: #16a34a14;
  --zui-command-content-lime-border: #65a30d;
  --zui-command-content-lime-bg: #65a30d14;
  --zui-command-content-mint-border: #10b981;
  --zui-command-content-mint-bg: #10b98114;
  --zui-command-content-ocean-border: #0284c7;
  --zui-command-content-ocean-bg: #0284c714;
  --zui-command-content-sapphire-border: #1d4ed8;
  --zui-command-content-sapphire-bg: #1d4ed814;
  --zui-command-content-lavender-border: #8b5cf6;
  --zui-command-content-lavender-bg: #8b5cf614;
  --zui-command-content-ruby-border: #be123c;
  --zui-command-content-ruby-bg: #be123c14;
  --zui-command-content-red-border: #dc2626;
  --zui-command-content-red-bg: #dc262614;
  --zui-command-content-slate-border: #475569;
  --zui-command-content-slate-bg: #47556914;
  --zui-command-content-zinc-border: #52525b;
  --zui-command-content-zinc-bg: #52525b14;
  --zui-command-content-stone-border: #57534e;
  --zui-command-content-stone-bg: #57534e14;
  --zui-command-content-royal-border: #4338ca;
  --zui-command-content-royal-bg: #4338ca14;
  --zui-command-content-electric-border: #0ea5e9;
  --zui-command-content-electric-bg: #0ea5e914;
  --zui-command-content-forest-border: #166534;
  --zui-command-content-forest-bg: #16653414;
  --zui-command-content-sunset-border: #ea580c;
  --zui-command-content-sunset-bg: #ea580c14;
  --zui-command-content-magenta-border: #c026d3;
  --zui-command-content-magenta-bg: #c026d314;
  --zui-command-content-crimson-border: #b91c1c;
  --zui-command-content-crimson-bg: #b91c1c14;
  --zui-command-content-aqua-border: #0f766e;
  --zui-command-content-aqua-bg: #0f766e14;
  --zui-command-content-plum-border: #7e22ce;
  --zui-command-content-plum-bg: #7e22ce14;
}

/* Dark theme variables follow the same names with -dark appended. */
.dark {
  --zui-command-overlay-bg-dark: oklch(12.9% 0.042 264.695 / 0.6);
  --zui-command-trigger-border-dark: #ffffff1a;
}

What it does

Render a portal dialog with a search input, grouped items, separators, and an empty state.

Filtering, active-item tracking, and keyboard navigation are handled internally.

Composition and API

Compose Command with CommandTrigger, CommandContent, CommandInput, CommandList, CommandGroup, CommandItem, CommandSeparator, CommandEmpty, and CommandFooter. Use appearance and size variants for visual tone, and the hotkey prop for a global shortcut.

Common use cases

Global Cmd+K navigation across pages and resources.
Quick action launchers in dashboards and developer tools.
Searchable menus that combine navigation and commands.
Keyboard-driven workflows for power users.

Accessibility

The palette renders role=dialog with aria-modal, traps focus while open, restores focus on close, and exposes the input as a combobox with role=option items. Provide a label for the dialog.

Next.js integration notes

Use Command inside client components since it manages open state and key handlers in the browser. The base entry stays free of framer-motion; import CommandContentAnimated only where you want motion.

FAQ

Does Command support a global Cmd+K shortcut?

Yes. Set the hotkey prop (defaults to k) and the palette binds meta/ctrl + key to toggle open from anywhere.

How does keyboard navigation work?

Arrow Up and Down move the active item, Enter selects it and fires onSelect, and Escape closes the palette. Typing filters items by value and keywords.

Is there an animated command palette?

Yes. Import CommandContentAnimated from the animated entrypoint to spring the palette in; it falls back to a fade when reduced motion is preferred.