Every action, one keystroke.

CommandPalette.register([
  { id: 'save', label: 'Save file',
    hint: 'Ctrl+S', group: 'Actions',
    action: function () { save() } }
])   // Ctrl/Cmd+K just works

{ id: 'docs', label: 'Open documentation',
  keywords: 'help manual guide' }

{ id: 'theme-dark', label: 'Theme: Dark',
  group: 'Theme',
  action: function () { setTheme('dark') } }

CommandPalette.defaults.recent = true

CommandPalette.register({ id: 'secret', … })
CommandPalette.unregister('secret')

<script src="https://cdn.jsdelivr.net/gh/
  vanilla-ui-kit/components/command/command.js">
</script>

---

API reference

The complete surface of CommandPalette (v1.0.0), as implemented in command.js. Zero dependencies, CommonJS/AMD/global builds, SSR-safe (every method is a no-op without a DOM).

• Usage
• Options
• Methods
• Statics
• Events & callbacks
• Declarative init
• Theming
• Accessibility

Constructor & usage

var palette = new CommandPalette(options)   // options object, optional — every key optional

The constructor stores options (merged over CommandPalette.defaults), registers any commands passed in, and binds the global hotkey immediately (unless hotkey: false). The overlay DOM and stylesheet are only built and injected on the first open().

Three ways to use it:

• Static registry (zero setup) — CommandPalette.register(command) and the other statics proxy a lazily created default instance; nothing is constructed or bound until the first static call. Change any default first via CommandPalette.defaults.placeholder = '…'.
• Instances — new CommandPalette({ commands: […], hotkey: 'ctrl+shift+p', … }) for a palette with its own options, hotkey, and command set.
• Declarative opener — any element with data-command-open opens the default palette on click (see Declarative init).

Command object shape

Passed to register() (single object or array). Only id is required — entries without an id are silently skipped. Re-registering an existing id replaces the old command in place (list order stays stable).

The palette closes before calling action, so the action can open a modal or move focus without fighting the palette. With recent: true the last 5 run commands appear in a “Recent” group at the top of the empty-query view — in memory only, per page load; nothing is stored.

Matching

Case- and diacritic-insensitive subsequence match over label + keywords (spaces in the query are ignored). Scoring favors consecutive runs, word-starts (so sf finds Save File), and matches near the start of the label; keyword hits rank a shade below equal label hits and are never highlighted. Results are sorted by score (registration order breaks ties) and capped at maxResults. With an empty query all commands are shown, grouped in first-registration order.

Options

Every key of CommandPalette.defaults, plus the constructor-only commands key. Options are shallow-copied over the defaults (labels is merged one level deep); keys set to undefined are ignored. Mutate CommandPalette.defaults before the first static call to configure the default palette.

The labels keys

Instance methods

All methods return the instance, so calls chain. Readable instance properties: isOpen (boolean) and commands (the normalized command array).

Statics & helpers

CommandPalette.register / unregister / open / close / toggle proxy a lazily created default instance — nothing is built or bound until the first call — and return CommandPalette for chaining.

Events & callbacks

The palette dispatches no DOM events — all notification is via option callbacks and the per-command action:

In all callbacks, command is the normalized command object ({ id, label, hint, group, icon, keywords[], action, disabled }) and palette is the instance the command ran on.

Declarative init

There is exactly one declarative hook: any element with a data-command-open attribute opens the default palette on click. Wiring happens automatically on DOMContentLoaded (or immediately if the script loads after DOM ready); for content added later, call CommandPalette.autoInit(root) — elements are only wired once. Commands themselves cannot be declared via data-* attributes; registration is JavaScript-only.

<button type="button" data-command-open>Open command palette</button>

<script>
  // after injecting new markup:
  CommandPalette.autoInit(document.getElementById('late-content'))
</script>

Theming

Auto light/dark with the family's resolution order: <html data-theme> / data-bs-theme / .dark/.light class → prefers-color-scheme, re-resolved live (via the VC core's watcher when loaded, otherwise a private MutationObserver + media-query listener). Pin it with CommandPalette.defaults.theme = 'dark'. All colors are CSS custom properties on the .vcmd root:

.vcmd { --vcmd-accent: #b45309; --vcmd-radius: 10px; }   /* your overrides */

With the VC core loaded, VC.config({ accent: '#b45309' }) themes the palette and every other family component in one call.

CSS isolation: the overlay renders as class="vcmd vc1" and all structural rules ship salted (.vcmd.vc1 .vcmd-option { … }) so host-page design systems can't override the palette — while the --vcmd-* variable overrides above keep working (variable definitions are deliberately unsalted). Custom token: CommandPalette.salt = 'acme' before the first open; disable with CommandPalette.salt = false.

Headless: set CommandPalette.defaults.styles = false (or per instance styles: false) and no CSS is ever injected. You keep the full behavior — fuzzy matching, keyboard model, ARIA, recent group — and style the markup contract below entirely from your own CSS. The stock stylesheet is available as a starting point via CommandPalette.css (string) or dist/command.css (file).

.vcmd[data-theme="dark"].vcmd-open      ← .vcmd-out while leaving
  .vcmd-backdrop
  .vcmd-panel                           ← role=dialog
    .vcmd-search
      .vcmd-glass                       ← magnifier SVG
      .vcmd-input                       ← role=combobox
    .vcmd-list                          ← role=listbox
      .vcmd-group                       ← section header (role=presentation)
      .vcmd-option.is-active            ← role=option; .is-disabled
        .vcmd-icon                      ← only when `icon` given
        .vcmd-label                     ← .vcmd-mark spans wrap matches
        .vcmd-hint                      ← only when `hint` given
      .vcmd-empty                       ← only when nothing matches
    .vcmd-footer                        ← ↑↓ navigate · ↵ run · esc close

Accessibility & keyboard

Hotkey syntax

Simple modifier+…+key strings: 'mod+k' (default), 'ctrl+shift+p', 'alt+space'. mod means Cmd on macOS, Ctrl everywhere else; other modifier aliases are ctrl/control, shift, alt/option, and meta/cmd/command/win. Set hotkey: false to disable the global binding.

ARIA

• ARIA combobox/listbox pattern: the search input is role="combobox" with aria-expanded, aria-controls, aria-autocomplete="list", and aria-activedescendant pointing at the active role="option" row; group headers and the empty state are presentational.
• Focus is held in the input for the whole session (clicks inside the panel don't steal it; Tab is trapped); on close, focus returns to the element that was focused before opening.
• The panel is role="dialog" aria-modal="true" labeled by labels.title; the footer key legend is aria-hidden (the same keys are conveyed by the combobox semantics). Disabled options carry aria-disabled="true".
• Reduced motion is respected (prefers-reduced-motion: reduce disables all transitions).

var pal = new CommandPalette({
  styles: false,   // no CSS injected
  commands: [ /* … */ ]
})
openBtn.onclick = function () { pal.open() }

.vcmd { @apply fixed inset-0 z-50 flex items-start
  justify-center p-4 pt-[10vh] font-sans; }
.vcmd-backdrop { @apply absolute inset-0
  bg-slate-950/70 backdrop-blur-sm; }
.vcmd-panel { @apply relative z-10 w-full max-w-lg
  overflow-hidden rounded-2xl border border-white/10
  bg-slate-900 text-slate-200 shadow-2xl; }
.vcmd-search { @apply flex items-center gap-3
  border-b border-white/10 px-4 py-3; }
.vcmd-input { @apply w-full border-0 bg-transparent
  text-base text-slate-100 outline-none; }
.vcmd-list { @apply max-h-72 overflow-y-auto p-2; }
.vcmd-group { @apply px-3 pt-3 pb-1 text-[11px]
  font-semibold uppercase tracking-widest text-slate-500; }
.vcmd-option { @apply flex cursor-pointer items-center
  gap-3 rounded-lg px-3 py-2.5 text-sm; }
.vcmd-option.is-active { @apply bg-amber-400/10 text-amber-300; }
.vcmd-option.is-disabled { @apply opacity-40 cursor-not-allowed; }
.vcmd-mark { @apply rounded-sm bg-amber-400/20 text-amber-200; }
.vcmd-hint { @apply text-xs text-slate-500; }
.vcmd-empty { @apply px-3 py-10 text-center text-slate-500; }
.vcmd-footer { @apply flex gap-4 border-t border-white/10
  px-4 py-2 text-[11px] text-slate-500; }
.vcmd-key { @apply rounded border border-white/15 bg-white/5
  px-1.5 py-0.5 font-mono text-[10px] text-slate-400; }