--- title: Command Palette description: Searchable command palette (⌘K) visibility: guest draft: false --- # Command Palette The `` component creates a spotlight-style search modal activated by a keyboard shortcut (Cmd+K / Ctrl+K by default). It implements the [WAI-ARIA Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) with grouped results and keyboard navigation. ## Usage :::preview{title="Command Palette"}
Dashboard Projects Profile Appearance Open Command Palette
::: :::source{language="blade"} {{-- The preview above is boxed into a fixed-height frame and opts out of teleporting so it can render inside the page. Yours needs neither: the defaults teleport the panel to the body and lock background scroll. --}} Dashboard Projects Profile Appearance Open Command Palette ::: ## Basic Setup ```blade Dashboard Projects Profile Appearance No results found. Navigate with arrow keys ``` ## Custom Hotkey Change the keyboard shortcut that opens the palette: ```blade {{-- Default: Cmd+K (macOS) / Ctrl+K (Windows/Linux) --}} {{-- Alternative: Ctrl+/ --}} {{-- Forward slash only (like GitHub) --}} ``` ## Items with Shortcuts Display keyboard shortcuts alongside items for discoverability: ```blade New Project Search Files ``` ## Disabled Items ```blade Export (coming soon) ``` Disabled items are visually muted, skipped by keyboard navigation, and have `aria-disabled="true"`. ## Empty State The `command-palette.empty` sub-component is shown when the search query matches no items: ```blade No results found. Try a different search term. ``` ## Programmatic Open/Close ```blade $this->dispatch('wirekit-command-palette-show'); ``` ## Width & Layout The command palette has a fixed max-width of 32rem (512px) and is centered near the top of the viewport — following the established macOS Spotlight pattern. The results list grows with content up to **18rem (288px)** and scrolls beyond that. Two variables move it, and neither needs a build step: | Variable | Default | What it moves | | --- | --- | --- | | `--wk-command-palette-list-max-height` | `18rem` | How tall the results list gets before it scrolls | | `--wk-command-palette-offset-top` | — | How far below the top of the viewport the panel sits | ```blade {{-- 1. A palette showing ranked search results wants more room than a short command list does — roughly half the viewport reads well. --}}
{{-- items --}}
``` Set it on any ancestor; it inherits. For a whole-application change, put it on `:root` in your stylesheet. ## Behavior - **Keyboard shortcut** listener is registered globally on `document` and respects modifier keys - **[Focus trap](https://github.com/focus-trap/focus-trap)** (bundled ~3.8 KB) keeps keyboard navigation within the palette - **Scroll lock** hides body scrollbar while the palette is open - **Teleport** renders the palette at `` level for correct stacking - **You own the result set** -- the palette renders exactly the items you pass and does **not** filter them itself. Wire the search query to your own filtering (server-side or client-side) via the query event below - **Livewire SPA** navigation (`wire:navigate`) automatically closes open palettes - **Transitions** use scale + opacity for smooth open/close animation ## Server-Side Search The palette renders whatever items you give it — it never filters them itself. To drive a live, server-backed search, listen for the `wirekit-command-palette-query` event: it fires on every keystroke (debounced 300 ms) and carries the current query in `event.detail.query`. Feed that query to Livewire, re-query your data, and re-render the item list: ```blade {{-- 1. Listen on the palette itself — the event is dispatched from its root. --}} {{-- 2. Render the server-filtered results. Livewire swaps this list as `search` changes. Give each item a stable id so the list keeps its identity across re-renders. --}} @foreach ($results as $result) {{ $result->title }} @endforeach ``` ```php // 3. In the Livewire component: re-query whenever `search` updates. public string $search = ''; public function getResultsProperty(): Collection { // Debounced upstream by the event, so this runs at most ~3×/second while typing. return Command::search($this->search)->take(20)->get(); } ``` From a Livewire component, use the **full** event name — Livewire rewrites `wire:` to `x-on:` verbatim, so the `wirekit-` prefix has to be there: ```blade ``` The event bubbles, so a listener on any ancestor works too — but the palette itself is the natural place, and it is where it now fires from. ### Keeping the list stable while it re-renders Server-side search rebuilds the item list on every keystroke, which puts two things at risk. Both are handled, and one needs something from you: - **Item identity — pass an `id`.** The item id anchors the combobox's `aria-activedescendant`. Derived automatically from the item's `href`, or its text when there is no href; pass `:id` explicitly when you have a real key. Without a stable id the screen reader's announcement target moves on every keystroke and Livewire's morph patches every row. - **Keyboard selection.** When the results change, the highlight is cleared rather than left pointing at whatever now occupies that position — so Enter can never activate a row the reader never saw. When the same results merely re-render, the highlight is restored (morph strips it, because the highlight lives only in the browser). ## Props ### `` | Prop | Type | Default | Description | | --- | --- | --- | --- | | `hotkey` | `string` | `'cmd+k'` | Keyboard shortcut to open the palette | | `placeholder` | `string` | `'Search commands...'` | Placeholder text for the search input | | `teleport` | `bool` | `true` | Teleport the overlay to `` so it sits above every stacking context. Set to `false` to render the overlay inline — required when embedding the palette inside a scoped container (e.g. docs preview cards with `contain: layout`) | | `lockScroll` | `bool` | `true` | Lock `document.body` scroll while the palette is open (standard modal behavior). Set to `false` when the palette is embedded inside a local container and you want the rest of the page to stay scrollable and interactive | | `scope` | `string\|null` | `null` | Scoped personalization key | ### `` | Prop | Type | Default | Description | | --- | --- | --- | --- | | `heading` | `string` | **required** | Group label displayed above items | ### `` | Prop | Type | Default | Description | | --- | --- | --- | --- | | `href` | `string\|null` | `null` | URL (renders `` instead of `