Skip to content

OrigamCommandPalette ​

<OrigamCommandPalette> is a ⌘K-style command launcher in the spirit of Linear, Vercel and cmdk.paco.me. It opens an overlay, exposes a search input, fuzzy-matches a registered list of actions, and lets the user trigger one with a single keystroke.

The palette is keyboard-first:

  • Global hotkey toggles it open (defaults to ⌘+K on macOS, Ctrl+K on Windows / Linux).
  • ↑ / ↓ move the highlighted command.
  • Enter runs the highlighted command.
  • Esc closes the palette.
  • Focus is trapped inside the dialog while it is open and restored to the previously focused element on close.

Quick start ​

Declarative (props) ​

vue
<template>
    <OrigamBtn text="Open palette" @click="open = true"/>
    <OrigamCommandPalette v-model="open" :commands="commands"/>
</template>

<script setup lang="ts">
    import { ref } from 'vue'
    import type { ICommand } from '@origam/interfaces'

    const open = ref(false)

    const commands: ICommand[] = [
        {
            id: 'goto-settings',
            label: 'Go to settings',
            icon: 'mdi:cog',
            kbd: ['meta', 'shift', 's'],
            group: 'Navigation',
            perform: () => router.push('/settings')
        },
        {
            id: 'toggle-theme',
            label: 'Toggle theme',
            description: 'Switch between light and dark',
            kbd: ['meta', 'shift', 't'],
            group: 'Settings',
            keywords: ['dark', 'light'],
            perform: () => theme.toggle()
        }
    ]
</script>

Composable (global registry) ​

For commands that originate in feature code, register them through useCommand(). Entries are auto-unregistered when the surrounding component unmounts.

ts
import { useCommand } from '@origam/composables'

const { register, open } = useCommand()

register({
    id: 'project.create',
    label: 'Create project',
    icon: 'mdi:plus',
    kbd: ['meta', 'shift', 'p'],
    group: 'Actions',
    perform: () => createProject()
})

// Open the palette imperatively from anywhere.
open()

When <OrigamCommandPalette> is mounted without an explicit commands prop, it reads from the global registry. Multiple components addressing the same singleton share the same command list — by design, the registry is process-wide.

Typography ​

fontSize drives the font size of two BEM surfaces simultaneously. The prop maps a primitive font token key to the matching component CSS variable via useTypography.

SurfaceCSS variableEffective props
__input (search field)--origam-command-palette__input---font-sizefontSize
__group-title (group header)--origam-command-palette__group-title---font-sizefontSize

fontFamily, fontWeight, lineHeight and letterSpacing were removed from ICommandPaletteProps (issue #501): fontWeight and letterSpacing have hardcoded values in the SCSS (600 and 0.04em on __group-title, NOT token-driven), lineHeight has no matching SCSS rule on either surface, and fontFamily is a project-level setting configured once on OrigamApp.

vue
<OrigamCommandPalette v-model="open" :commands="commands" font-size="sm"/>

Props ​

PropTypeDefaultDescription
modelValuebooleanfalseWhether the palette is open. v-model.
hotkeystring[] | string[][] | null[['meta','k'],['ctrl','k']]Global hotkey(s) that toggle the palette. Pass null to disable.
commandsICommand[]—Static command list. Falls back to the global registry when omitted.
filterboolean | (commands: ICommand[], query: string) => ICommand[]trueHow commands are filtered against the query. true: built-in fuzzy match (see Fuzzy matching). false: commands are shown as given, in the given order. A function: its return value is shown, in its order. With false or a function the list is flat (no group headers) while the query is non-empty, nothing is highlighted, and commands is honoured even when empty (no fallback on the useCommand() registry).
placeholderstring'origam.command_palette.placeholder'Placeholder of the search input, and the name the role="combobox" input and the listbox are announced with. Resolved through the locale catalogue — pass a key to translate, or literal text to render verbatim (an unknown key is returned unchanged).
emptyTextstring'origam.command_palette.empty_text'Empty-state message when no command matches the query. Same key-or-literal contract as placeholder.
maxHeightnumber | string480Max height of the result list (px when number).
widthnumber | string640Width of the palette dialog (px when number).
loadingbooleanfalseDisplay a loader inside the result list.
searchIconTIcon'mdi:mdi-magnify'Icon of the search field. Accepts an icon id, an SVG path string or a component. The search-icon slot takes precedence.
loadingIconTIcon'mdi:mdi-loading'Icon shown while loading is true. The loading slot takes precedence.
closeOnSelectbooleantrueClose the palette automatically when a command is selected.
closeOnEscapebooleantrueClose on Escape.
closeOnBackdropbooleantrueClose when the user clicks the backdrop.
attachboolean | string | Elementfalse (→ document.body)Teleport target, resolved through useTeleport() — same semantics as OrigamOverlay.attach. true renders in place; a CSS selector string or an Element teleports there instead of document.body.
fontSizeTFontSize—Font size token applied to both __input and __group-title surfaces.

Events ​

EventPayloadDescription
update:modelValuebooleanOpen/close state change.
selectICommandFired when the user runs a command (click or Enter).
querystringFired on every input keystroke — connect to a debounced async fetch.

Slots ​

SlotPropsDescription
item{ command, isActive }Replace a single command row. Useful for avatars / rich rendering.
empty—Replace the default empty state.
search-icon—Replace the search field icon (takes precedence over searchIcon).
loading—Replace the loader shown while loading is true (takes precedence over loadingIcon).
footer—Replace the default footer hints.

ICommand interface ​

ts
interface ICommand {
    id: string                  // stable id, dedup key in the registry
    label: string               // primary label
    description?: string        // secondary line under the label
    icon?: TIcon                // prepend icon
    kbd?: string[]              // shortcut shown through <OrigamKbd>
    group?: string              // e.g. 'Navigation' — drives the group subheader
    keywords?: string[]         // extra search terms
    perform: () => void | Promise<void>
    disabled?: boolean
}

Composable — useCommand() ​

ts
const {
    register,    // (cmd) => unregister closure; auto-cleans on scope dispose
    unregister,  // (id) => void
    commands,    // ComputedRef<readonly ICommand[]>
    open,        // () => void
    close,       // () => void
    isOpen       // Ref<boolean>
} = useCommand()
  • The registry is a process-wide singleton. Every caller sees the same list. Re-registering with an existing id replaces the entry — no duplicates.
  • When register() is called inside a Vue effect scope (component setup, custom scope), the entry is automatically unregistered when the scope disposes (component unmount, route leave, …). Outside a scope, you must call unregister(id) yourself or invoke the closure returned by register().

Fuzzy matching ​

The palette ships with a built-in subsequence-based matcher (fuzzyMatch in src/utils/CommandPalette/fuzzy-match.util.ts). It walks the query character-by-character against the haystack (label + keywords + description) and computes a score from:

  • Consecutive-run bonus — runs of contiguous query chars in the haystack rank higher than spread-out matches.
  • First-label-hit bonus — earlier matches in the label outrank late matches.
  • Label-prefix bonus — labels that start with the query get a flat bonus on top.

Ties fall back to registration order (stable). Empty query short-circuits to "return everything in declaration order" so the user always has a list to navigate.

No external dependency — fuse.js / match-sorter would add ~20 KB gzipped for a feature we can match in 100 lines of pure TS.

Externally ranked results (filter) ​

For a server-side or full-text search, feed the results through the query event and turn the built-in matcher off, otherwise a hit found by body text (not present in label / keywords / description) is dropped and the engine's ranking is re-sorted:

vue
<origam-command-palette
    v-model="open"
    :commands="hits"
    :filter="false"
    @query="q => hits = fullTextSearch(q)"
/>

:filter="(commands, query) => commands.filter(...)" applies your own filter and order instead. The grouping, keyboard navigation (aria-activedescendant) and empty state behave the same as with the built-in matcher.

Hotkey configuration ​

PlatformDefault trigger
macOS⌘ + K (['meta', 'k'])
Windows / LinuxCtrl + K (['ctrl', 'k'])

The component installs both by default — useHotkey itself normalises meta vs ctrl per platform, but binding both forms is safe and covers fringe input-method combinations.

Override:

vue
<!-- Single combination -->
<OrigamCommandPalette v-model="open" :hotkey="['meta', 'shift', 'p']"/>

<!-- Multiple combinations -->
<OrigamCommandPalette v-model="open" :hotkey="[['meta', 'k'], ['meta', 'shift', 'p']]"/>

<!-- Disable the global listener -->
<OrigamCommandPalette v-model="open" :hotkey="null"/>

The listener is NOT triggered when focus is inside an INPUT, TEXTAREA or contentEditable element — this matches the behaviour of useHotkey({ inputs: false }). ⌘K typed in a regular text field never hijacks the user.

Accessibility ​

The palette implements the ARIA combobox pattern.

ElementRoles / attributes
Overlay rootrole="dialog" + aria-modal="true" + aria-label naming the dialog ("Command palette", origam.command_palette.aria_label)
Search inputrole="combobox" + aria-expanded + aria-controls + aria-activedescendant + aria-autocomplete="list"
Results containerrole="listbox"
Each commandrole="option" + aria-selected + aria-disabled

Note (issue #404): the dialog used to point aria-labelledby at the search input, relying on the input's placeholder to supply a name. Measured against real Chromium via Playwright's ariaSnapshot(): this produced an UNNAMED dialog — a placeholder names the element that carries it, not an element that merely references it via aria-labelledby. aria-label on the dialog itself is the fix.

The dialog also:

  • Traps Tab focus inside the palette (Tab returns to the input — there is no escape route while open).
  • Restores focus to the element that was focused before the palette opened when it closes — same pattern as OrigamDialog.
  • Honours prefers-reduced-motion by collapsing the fade-in transition.

Design tokens ​

CSS variableDescription
--origam-command-palette---z-indexStacking order (default modal).
--origam-command-palette---widthDialog width.
--origam-command-palette---max-heightMax height of the result list.
--origam-command-palette---background-color / ---color / ---border-color / ---border-radius / ---box-shadowDialog surface tokens.
--origam-command-palette__input---padding / ---font-size / ---icon-color / ---placeholder-colorSearch input tokens.
--origam-command-palette__item---padding / ---height / ---border-radiusResult item tokens.
--origam-command-palette__item---background-color-active / ---color-activeActive-row styling.
--origam-command-palette__group-title---color / ---font-size / ---paddingGroup header tokens.
--origam-command-palette__empty---colorEmpty state color.
--origam-command-palette__footer---padding / ---color / ---border-colorFooter tokens.
--origam-command-palette--backdrop---background-color / ---backdrop-filterOverlay backdrop.