CommandPalette

Navigation
stable

⌘K-style command launcher overlay with fuzzy search, hotkey registration and a plugin registry via useCommand().

Structure

Anatomy

Visual breakdown of the component's internal structure with BEM class call-outs.

Anatomy of OrigamCommandPaletteSchematic of the CommandPalette component with numbered internal parts. 1 Type a command… 2 3 NAVIGATION 4 Go to Settings ⌘K 5 6 ① = backdrop (fixed / inset 0). ② = dialog (role="dialog"). ③ = group-title. ④ = item (role="option"). ⑤ = empty slot. ⑥ = footer.
Anatomy of <origam-command-palette> — 6 internal regions. The backdrop ① is a fixed scrim with blur; the dialog ② contains the search bar, listbox, and footer.
1.origam-command-palette__search
Search bar row. Contains a magnify icon and a <input role="combobox">.
2.origam-command-palette__dialog
Dialog panel (role="dialog" aria-modal="true"). Width controlled by --origam-command-palette---width.
3.origam-command-palette__group-title
Group subheader. Rendered for each distinct group value on commands.
4.origam-command-palette__item
Command row (role="option"). Active row receives the active background token. Hosts icon, label, description and kbd hint.
5.origam-command-palette__empty
Empty-state container. Rendered when no commands match. Replaced by the #empty slot.
6.origam-command-palette__footer
Footer bar with keyboard shortcut hints (↑↓ navigate, ↵ select, Esc close). Replaced by the #footer slot.

API

Props

All props accepted by this component, with their type, default value and description.

modelValue
boolean
v-model controlling whether the palette is open.
hotkey
TCommandPaletteHotkey | null
[['meta', 'k'], ['ctrl', 'k']]
Global hotkey(s) that toggle the palette open. Defaults to ⌘K / Ctrl+K. Pass null to disable the global listener.
commands
ReadonlyArray<ICommand>
Static command list. When omitted the palette uses commands registered via the useCommand() global registry.
filter
TCommandPaletteFilter
placeholder
string
Placeholder text inside the search input (already-translated string).
emptyText
string
Empty-state message displayed when no command matches the current query.
maxHeight
number | string
Maximum height of the result list. Number is interpreted as px.
width
number | string
Width of the palette dialog. Number is interpreted as px.
loading
boolean
false
Displays a loader inside the result list while async commands are being fetched.
searchIcon
TIcon
loadingIcon
TIcon
closeOnSelect
boolean
true
Closes the palette automatically when a command is selected.
closeOnEscape
boolean
true
Closes the palette when the user presses Escape.
closeOnBackdrop
boolean
true
Closes the palette when the user clicks the backdrop overlay.
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
fontSize
TFontSize
attach
boolean | string | Element | null

API

Slots

Content slots exposed by this component.

#item
Custom renderer for each result row. Exposes the command data and whether it is currently highlighted.
#empty
Custom empty state shown when no commands match the query.
#search-icon
#loading
#footer
Optional footer rendered below the result list (e.g. keyboard shortcut hints).

API

Emits

Events emitted by this component.

@update:modelValue
boolean
Fired when the open state changes (open/close).
@select
ICommand
Fired when the user selects a command from the result list.
@query
string
Fired on every keystroke as the search query changes. Use for async command fetching.

API

Exposed members

Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.

Ref<string>
Reactive current search query string.
ComputedRef<ICommand[]>
Computed list of commands that match the current query.
Ref<number>
Index of the currently highlighted command item in the filtered list.
Ref<boolean>
Whether the palette is currently open.

Customisation

CSS variables

CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.

Stack order of the fixed backdrop.
Vertical offset from the top of the viewport to the dialog panel.
Width of the dialog panel. Clamped to calc(100vw - 32px) on small screens.
Dialog panel background color.
Dialog panel foreground color.
Dialog panel border-radius.
Box shadow on the dialog panel.
Semi-transparent backdrop color.
Backdrop blur applied to the fixed scrim.
Background of the currently highlighted command item.

Inclusion

Accessibility

ARIA roles, keyboard navigation and focus management. Sourced from the real component template.

ARIA roles

dialog
combobox
listbox
option

Keyboard interactions

Keyboard interactions
KeyAction
↑ / ↓Move highlight between command items in the result list.
EnterExecute the currently highlighted command.
EscapeClose the palette (when closeOnEscape=true).
⌘K / Ctrl+KToggle the palette open from anywhere in the page (global hotkey).

Notes

  • The search input uses role="combobox" with aria-controls pointing to the listbox, aria-expanded reflecting whether results are shown, and aria-activedescendant tracking the highlighted option.
  • The dialog panel uses role="dialog" aria-modal="true" and aria-labelledby pointing to the search input id. Focus is trapped inside while the palette is open.
  • Disabled commands have aria-disabled="true" and cannot be selected via keyboard or mouse.

Foundation

Design tokens

Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.

Source
color
var(--origam-color__surface---raised)
Dialog panel background.
dimension
var(--origam-radius---lg)
Dialog panel border-radius.
shadow
var(--origam-shadow---xl)
Dialog panel elevation shadow.
color
var(--origam-color__action--secondary---bg)
Active item background.
dimension
640px
Default dialog width.
color
rgba(0, 0, 0, 0.45)
Backdrop overlay color.

Interactive

Playground

Edit props live and see the component update in real time. The generated code snippet updates as you change values.

Rendering the live preview…

Usage

Examples

Ready-to-paste code snippets for your templates.

Basic usage

vue

Async commands

vue

Grouped commands

vue