@ailuracode/alpine-command

Headless command palette (Spotlight-style) store — searchable actions, groups, keyboard navigation, nested pages, async execution, aliases, and ARIA helpers.

Install

pnpm add @ailuracode/alpine-command @ailuracode/alpine-core alpinejs

Active item navigation uses inline helpers — no extra dependency.

Quick start

import Alpine from "alpinejs";
import { commandPlugin } from "@ailuracode/alpine-command";

Alpine.plugin(
  commandPlugin({
    searchStrategy: "substring",
    onRun(item) {
      console.log("Ran", item.id);
    },
    persistence: {
      maxRecent: 8,
      getRecent: () => JSON.parse(localStorage.getItem("recent-commands") ?? "[]"),
      setRecent: (ids) => localStorage.setItem("recent-commands", JSON.stringify(ids)),
    },
  })
);
Alpine.start();

Store API

Member	Description
`open()` / `close()` / `toggle()`	Palette visibility
`isOpen`	Whether the palette is open
`search`	Reactive filter string
`activeIndex`	Keyboard-highlighted row
`filteredItems` / `visibleItems`	Visible commands for the current page
`groupedItems`	Filtered items grouped by `group`
`register(item)`	Register an action; returns `unregister()`
`run(id)` / `cancelRun()`	Execute or cancel in-flight async work
`pushPage(page)` / `goBack()`	Nested command pages
`executionState` / `runningId`	Async execution state
`inputProps()` / `listboxProps()` / `optionProps(id)`	Headless ARIA props
`handleKeydown(event)`	Typing, Backspace, Arrow/Home/End/Enter/Escape

Command item

{
  id: "toggle-theme",
  label: "Toggle theme",
  group?: "Appearance",
  shortcut?: "⌘K",
  keywords?: ["dark", "light"],
  aliases?: ["spotlight"],
  disabled?: false | (() => boolean),
  hidden?: false | (() => boolean),
  enabled?: true | (() => boolean),
  pinned?: false,
  page?: "root",
  load?: async () => {},
  action: () => {},
}

Search

Default strategy: substring ranking on label, aliases, keywords, group, and shortcut
searchStrategy: "fuzzy" enables lightweight fuzzy matching
rank(item, search) replaces the deprecated filter(item, search) boolean API

Disabled commands remain visible unless hidden is true. Keyboard navigation and run() skip disabled or loading commands.

Plugin options

Option	Default	Description
`id`	auto-generated	Controller identifier
`rank` / `searchStrategy`	substring	Ranker for the filter pipeline
`persistence`	—	Recent/pinned hooks (maxRecent, getRecent, setRecent, getPinned, setPinned)
`storeKey`	`'command'`	`$store` key the Alpine plugin registers under
`magicKey`	`'command'` (or `storeKey` when renamed)	`$command` magic key the Alpine plugin registers under

Avoiding name collisions

If your application already owns a $store.command or another toolkit plugin registers on that name, rename the integration surface without touching the controller:

Alpine.plugin(commandPlugin({
  storeKey: "palette",         // → $store.palette
  // magicKey follows storeKey by default → $palette
  magicKey: "cmd",             // explicit override → $cmd
}));

storeKey is the only argument most hosts need. magicKey moves independently only when both names must be freed. The exposed constants DEFAULT_COMMAND_STORE_KEY and DEFAULT_COMMAND_MAGIC_KEY keep the rename discoverable from TypeScript.

Integration

Overlay — optional overlayId documents a palette layer id for $store.overlay.zIndexOf(overlayId, layer)
Scroll — pass scroll: $store.scroll to lock page scroll while open (enabled by default when provided)
Keyboard — global open shortcuts remain consumer-owned; compose with @ailuracode/alpine-keyboard when needed
Dialog / Toast — render the palette in a dialog panel or call $toast() from action / onRun

Neither overlay, scroll, keyboard, dialog, nor toast is required.

SSR

Standalone usage

import { createCommandController } from "@ailuracode/alpine-command";

const command = createCommandController();
command.register({ id: "save", label: "Save", action: () => {} });
command.open();

Migration notes

register() now returns an unregister callback; unregister(id) remains available
filter is deprecated in favor of rank or searchStrategy
filteredItems now includes disabled commands; use itemState(id)?.disabled or visibleItems for runtime state

License

MIT

FilesExpand file tree

README.md

Latest commit

History