CommandPalette

<button type="button" data-command-open="apogee-command" class="rounded-md border border-neutral px-3 py-2 text-sm">Open (⌘K)</button>
<CommandPalette
commands={[
  { label: 'Create project', group: 'Actions', keywords: 'new add' },
  { label: 'Settings', href: '/settings', group: 'Navigate' },
  { label: 'Documentation', href: '/docs', group: 'Navigate' },
]}
/>

Add

npx @ava-ui/apogee add command-palette

No Apogee dependencies. Uses @lucide/astro internally (Search) for the input icon — no icon import needed in your usage.

Usage

---
import CommandPalette from '@/components/apogee/CommandPalette/CommandPalette.astro'
---
<button type="button" data-command-open="apogee-command">Search…</button>
<CommandPalette
  commands={[
    { label: 'Create project', group: 'Actions' },
    { label: 'Settings', href: '/settings', group: 'Navigate' },
  ]}
/>

Anatomy

• Dialog — native <dialog>; modal, backdrop, and closedby="any" come free.
• Search input — role="combobox", filters commands as you type.
• Groups — commands grouped by group, in first-seen order; ungrouped commands render without a heading.
• Options — role="option" buttons, one per command; an empty-state message shows when nothing matches.

API

@composable — exposed to Content Editors in AVA. No passthrough attrs — the dialog doesn’t spread ...rest.

Slots: empty replaces “No results.” (an EmptyState fits); footer is a row of key hints under the list, shown from md.

Rich commands

Icons, avatars, descriptions and shortcuts. Try typing “resume” (accents are ignored) or press ⌘⇧P / Ctrl+Shift+P anywhere on this page.

<CommandPalette id="rich-command" commands={[
{ label: 'New project', id: 'new-project', group: 'Actions', icon: FolderPlus, shortcut: ['alt', 'shift', 'n'] },
{ label: 'Résumé', group: 'Files', icon: FileText, description: 'Updated yesterday' },
{ label: 'Ana Lima', group: 'People', avatar: { name: 'Ana Lima' }, description: 'Product designer', stacked: true },
]}>
<EmptyState slot="empty" variant="plain" size="small" title="Nothing matches"><SearchX slot="icon" /></EmptyState>
<Fragment slot="footer"><span><Kbd>↑</Kbd> <Kbd>↓</Kbd> to move</span><span><Kbd>↵</Kbd> to select</span><span><Kbd>esc</Kbd> to close</span></Fragment>
</CommandPalette>

Long lists

A palette with hundreds of commands makes every page heavy. Pass src instead: the palette fetches the JSON the first time it opens and builds those commands then. This page’s palette loads all of these docs from /search.json. Commands from src take a label, link, group, keywords and description; icons, avatars and shortcuts stay with commands.

<CommandPalette id="docs-command" commands={[]} src="/search.json" />

States

• Closed — default; the dialog isn’t rendered visibly until opened.
• Open — backdrop + dialog fade in (@starting-style).
• Highlighted option — the active result (aria-selected), moved with arrow keys or reset to the first result on every filter.
• Empty — “No results.” (or the empty slot) shows when nothing matches the query; empty groups hide their heading.

Examples

Grouped commands with keywords (aliases the label doesn’t contain):

<CommandPalette
  commands={[
    { label: 'Create project', group: 'Actions', keywords: 'new add' },
    { label: 'Invite teammate', group: 'Actions', keywords: 'member user' },
    { label: 'Settings', href: '/settings', group: 'Navigate' },
  ]}
/>

A command with no href dispatches apogee:command for the app to handle:

---
// listen on the client:
// document.addEventListener('apogee:command', (e) => { ... e.detail.id })
---
<CommandPalette
  id="app-command"
  commands={[{ label: 'Toggle theme', id: 'toggle-theme' }]}
/>

Custom shortcut key:

<CommandPalette shortcut="/" commands={[{ label: 'Search docs', href: '/docs' }]} />

Accessibility

• Native <dialog> gives a focus trap, Esc-to-close, and closedby="any" backdrop-click-to-close for free.
• role="combobox" input wired with aria-expanded, aria-controls, aria-autocomplete="list"; results are role="option" with aria-selected.
• No JS: there is no fallback — the dialog, shortcut, and filtering are entirely JS-driven with no no-js: variant. Always give commands a real, independently reachable trigger (a visible link or menu item) alongside the palette.

Tokens

Do / Don’t

• Do keep commands reasonably sized — filtering is a client-side substring match against label + keywords, so very large lists get sluggish.
• Do use keywords for synonyms a user might type instead of the exact label.
• Don’t mount two palettes with the same shortcut on one page — the first keydown listener wired wins.
• Don’t treat the palette as the only way to reach a command — always pair it with a visible trigger.

Content

• Command labels are short: verb-led when they act (“Create project”), noun-led when they navigate (“Settings”).
• Group names are short category nouns, sentence case.
• placeholder states what can be typed; the default (“Type a command or search…”) works for most cases.