CommandPalette

Searchable command list with grouping and an optional keyboard shortcut.

Overview

  • Provide a command search alongside regular navigation. Keep commands reachable without the shortcut.

Aliases

command menu, quick actions

When to use

  • Use CommandPalette to search a set of actions.
  • Use sections and keywords so the palette stays searchable as the command set grows.

When not to use

  • Do not use CommandPalette as a replacement for everyday primary navigation.
  • Do not hide essential first-run actions behind the palette alone.

Structural parts

command shell

surface

Centered overlay surface that owns the filter input and result list.

command query

input

Query input that filters commands.

command option

item

Single command row with optional section and shortcut metadata.

Public interface

Props
NameTypeDefaultDescription
openbooleanfalseControlled open state.
itemsArray<{ id: string; label: string; section?: string; shortcut?: string; keywords?: string[]; disabled?: boolean }>—Command definitions available in the palette.
querystring''Controlled query string.
placeholderstring'Search commands'Query input placeholder.
emptyTitlestring'No commands found'Heading shown when filtering returns no results.
emptyDescriptionstring'Change or clear the search.'Optional empty-state guidance.
hotkey'mod+k' | falsefalseEnables or disables the global mod+k shortcut.
onOpenChange(detail: { open: boolean }) => void—Runs when the palette opens or closes.
onQueryChange(detail: { query: string }) => void—Runs when the query changes.
onAction(detail: { id: string }) => void—Runs when a command is executed.
themeThemeContract—Sets the theme used to resolve component styles.
Events
NamePayloadDescription
openchange{ open: boolean }Fires when an overlay-style component opens or closes through user interaction.
querychange{ query: string }Fires when the filter query changes.
action{ id: string }Fires with the executed command ID.
Slots
NameDescription
defaultCommandPalette is data-driven and does not expose command item slots.

Variants, sizes, and states

Variants

  • default: One centered command shell with grouped results and optional hotkey.

Sizes

  • default: CommandPalette uses one width recipe tuned for search and action scanning.

States

  • closed: Palette hidden
  • open: Palette visible
  • highlighted: One command is active for keyboard execution

Accessibility

Semantics

  • Uses dialog-style overlay semantics with a searchable command list.

Keyboard

  • Arrow keys move focus, Enter runs the command, and Escape closes the palette. The optional mod+k shortcut opens it.

Screen readers

  • Command labels remain explicit, with grouped sections and disabled commands still announced clearly.

Checklist

  • Verify that the control has an accessible name.
  • Verify that keyboard focus is visible in every state and size.
  • Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

root

--dk-command-gap
0.5rem
--dk-command-offset
24px

backdrop

--dk-command-backdrop-bg
color-mix(in srgb, black 42%, transparent)

surface

--dk-command-surface-bg
#f2f5fb
--dk-command-surface-fg
#16181c
--dk-command-surface-border
#95989d
--dk-command-surface-shadow
0 10px 15px rgba(0, 0, 0, 0.06), 0 4px 6px rgba(0, 0, 0, 0.04)
--dk-command-surface-radius
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-command-surface-width
min(42rem, calc(100vw - 2rem))
--dk-command-surface-max-height
min(32rem, calc(100vh - 3rem))
--dk-command-surface-padding
0.75rem

input

--dk-command-input-bg
#f2f5fb
--dk-command-input-fg
#16181c
--dk-command-input-border
#95989d
--dk-command-input-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-command-input-block-size
48px
--dk-command-input-inline-padding
0.875rem
--dk-command-input-font-size
0.95rem

section

--dk-command-section-fg
#16181c
--dk-command-section-size
0.72rem

item

--dk-command-item-bg
#f2f5fb
--dk-command-item-fg
#16181c
--dk-command-item-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-command-item-min-height
44px
--dk-command-item-inline-padding
0.75rem

itemLabel

--dk-command-item-label-size
0.95rem
--dk-command-item-label-weight
600

itemMeta

--dk-command-item-meta-fg
#16181c
--dk-command-item-meta-size
0.75rem

empty

--dk-command-empty-fg
#16181c
--dk-command-empty-size
0.9rem

Examples

Starter

Filtered command runner

A centered command surface with grouped actions.

<CommandPalette open={isOpen} items={commands} onAction={(detail) => runCommand(detail.id)} />

Common patterns

Global mod+k launcher

Enable the shortcut when the app provides searchable commands.

<CommandPalette hotkey="mod+k" items={commands} open={isOpen} onOpenChange={(detail) => isOpen = detail.open} />

Edge cases

Externally controlled query

Control the query when search state also drives analytics or suggestions elsewhere in the app.

<CommandPalette open={isOpen} query={query} onQueryChange={(detail) => query = detail.query} items={commands} />

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

default

pass

  • Evidence: mathematical
  • Coverage: complete (4 / 4 declared kinds evaluated)
  • Declared: contrast, target, optionRow, anchoredSurface
  • Evaluated: contrast, target, optionRow, anchoredSurface
  • Contrast: 98.5 Lc
  • Target: 48 px
  • Rows: 44 px
  • Surface: 672 × 512 px

selected

pass

  • Evidence: mathematical
  • Coverage: complete (4 / 4 declared kinds evaluated)
  • Declared: contrast, target, optionRow, anchoredSurface
  • Evaluated: contrast, target, optionRow, anchoredSurface
  • Contrast: 98.5 Lc
  • Target: 48 px
  • Rows: 44 px
  • Surface: 672 × 512 px