Overlays

CommandPalette

Modal search overlay for keyboard-first command launching and navigation. Filtering is consumer-owned: the `items` snippet receives `{ query }` and renders only the matching rows.

import { CommandPalette } from '@lostgradient/cinder/command-palette';
overlaycommand
01

Overview

Modal search overlay for keyboard-first commands, destinations, and record jumpers.

Usage

svelte 
<script lang="ts">
  import CommandPalette from '@lostgradient/cinder/command-palette';
</script>

<CommandPalette />

Grouped Results

Command items register with the palette by DOM node, so grouped results can use valid nested list markup without changing keyboard navigation. Use a presentational outer list item, an inner ul[role="group"] with an accessible name, and CommandItem children inside that inner list.

svelte 
<CommandPalette bind:open label="Command palette">
  {#snippet items()}
    <li role="presentation" class="cinder-command-group">
      <span class="cinder-command-group__label">Recent files</span>
      <ul role="group" aria-label="Recent files">
        <CommandItem value="roadmap" onSelect={() => openRoadmap()}>Roadmap</CommandItem>
        <CommandItem value="settings" onSelect={() => openSettings()}>Settings</CommandItem>
      </ul>
    </li>
  {/snippet}
</CommandPalette>
Live preview
02

When to use

Use when
  • Exposing a global keyboard-first launcher for power-user actions and navigation.
  • Letting users search across heterogeneous results such as commands, pages, and records in one input.
Avoid when
  • Picking a single value bound to a form field — use combobox instead.
  • Showing a contextual action menu attached to a trigger — use dropdown instead.
03

Examples

Basic command palette

A minimal palette with three items opened by a button.

Grouped command palette

Command items grouped with named listbox sections.

Search, recent, and keyed actions

Cmd+K opens the palette. Three sections: filtered search results, recent items, and keyed actions separated by visual group headers.

04

Props

Props for command-palette
Name Type Default Required Bindable Description
open boolean false bind Bindable open state. The component mutates open = false on Escape, backdrop click, or any explicit close path, then fires onClose.
placeholder text 'Search…' Placeholder rendered inside the search input.
label text 'Command palette' Accessible name for the dialog, wired via aria-label.
query text '' bind Bindable search query. Mutated by the input's oninput handler. Exposed to the items snippet so consumers can filter. Reset to an empty string each time the palette opens.
onClose () => void Fired after any close path routed through the palette close lifecycle.
triggerRef HTMLElement | null null Element to restore focus to on close. Falls back to captureFocus().
items snippet req Receives the current query so consumers can filter.
empty snippet Rendered when zero items are registered after filtering.
footer snippet Optional footer, e.g. for keybinding hints. Not part of the listbox.