CommandPalette
⌘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.
<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
groupvalue 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
#emptyslot. - 6.origam-command-palette__footer
- Footer bar with keyboard shortcut hints (
↑↓navigate,↵select,Escclose). Replaced by the#footerslot.
API
Props
All props accepted by this component, with their type, default value and description.
- modelValueboolean
- v-model controlling whether the palette is open.
- hotkeyTCommandPaletteHotkey | 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.
- commandsReadonlyArray<ICommand>
- Static command list. When omitted the palette uses commands registered via the useCommand() global registry.
- filterTCommandPaletteFilter
- placeholderstring
- Placeholder text inside the search input (already-translated string).
- emptyTextstring
- Empty-state message displayed when no command matches the current query.
- maxHeightnumber | string
- Maximum height of the result list. Number is interpreted as px.
- widthnumber | string
- Width of the palette dialog. Number is interpreted as px.
- loadingbooleanfalse
- Displays a loader inside the result list while async commands are being fetched.
- searchIconTIcon
- loadingIconTIcon
- closeOnSelectbooleantrue
- Closes the palette automatically when a command is selected.
- closeOnEscapebooleantrue
- Closes the palette when the user presses Escape.
- closeOnBackdropbooleantrue
- Closes the palette when the user clicks the backdrop overlay.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- fontSizeTFontSize
- attachboolean | 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:modelValueboolean
- Fired when the open state changes (open/close).
- @selectICommand
- Fired when the user selects a command from the result list.
- @querystring
- 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
Keyboard interactions
| Key | Action |
|---|---|
| ↑ / ↓ | Move highlight between command items in the result list. |
| Enter | Execute the currently highlighted command. |
| Escape | Close the palette (when closeOnEscape=true). |
| ⌘K / Ctrl+K | Toggle 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.
- colorvar(--origam-color__surface---raised)
- Dialog panel background.
- dimensionvar(--origam-radius---lg)
- Dialog panel border-radius.
- shadowvar(--origam-shadow---xl)
- Dialog panel elevation shadow.
- colorvar(--origam-color__action--secondary---bg)
- Active item background.
- dimension640px
- Default dialog width.
- colorrgba(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
Async commands
Grouped commands