Overlays
Command palette
A Cmd/Ctrl+K search over grouped pages and actions with keyboard navigation. Mounted once in the app shell and opened from anywhere.
- Source
- src/components/ui/command.tsx
- Figma
- CommandPalette.
Usage
Included in the GliaKit boilerplate. Import it where you need it:
import { CommandPalette, openCommandPalette, type CommandItem,} from "@/components/ui/command";When to use
- Fast navigation between pages in an app with more than a handful of destinations.
- Exposing common actions (New project, Invite teammate) to keyboard users.
- Behind a search box in the sidebar, opened with openCommandPalette().
- For searching records or content on the server, build a dedicated search with results; the palette filters a fixed list in memory.
- Do not mount more than one CommandPalette: each instance listens for Cmd/Ctrl+K and the open event.
Examples
Sidebar search box
A search-field look-alike that calls openCommandPalette(). It opens the palette already mounted in the app shell.
Groups, icons and shortcut hints
Items are grouped by group in the order they appear. kbd is a display hint only; it does not bind the shortcut.
Routing from the app shell
How the boilerplate wires it: one AppCommandPalette in AppShell, navigating on select. Cmd/Ctrl+K toggles it from any page.
API reference
CommandPalette
Owns its open state. Mounting it registers a global Cmd/Ctrl+K listener (toggles the palette) and listens for openCommandPalette(). Mount it once, in the app shell.
| Prop | Type | Default | Description |
|---|---|---|---|
| items | CommandItem[] | - | Items to search. Filtered by label, grouped by group in the order they appear. |
| onSelect | (item: CommandItem) => void | - | Called after the palette closes, with the chosen item. Typically router.push(item.value). |
| placeholder | string | "Search…" | Placeholder for the search input. |
CommandItem
Type of each entry in items.
| Prop | Type | Default | Description |
|---|---|---|---|
| group | string | - | Group heading the item is listed under. |
| label | string | - | Visible text. This is what the query matches against. |
| value | string | - | Arbitrary payload, usually a route href. Also used as the React key, so keep it unique. |
| icon | React.ReactNode | - | Optional leading icon. Size it yourself, e.g. className="size-4". |
| kbd | string | - | Optional shortcut hint shown on the right, e.g. "G D". Display only: it does not bind the shortcut. |
openCommandPalette
Function. Dispatches the open event so the mounted palette opens. Safe to pass straight to onClick.
| Prop | Type | Default | Description |
|---|---|---|---|
| () | () => void | - | Takes no arguments. |
Accessibility
- Rendered in a Radix Dialog: focus is trapped while open, Escape closes it and focus returns to where it was.
- The dialog has a visually hidden title, "Command palette".
- The search input is focused on open. Arrow Up and Down move the highlight and Enter selects the highlighted item.
- Results are plain buttons, so Tab also reaches them. The input has no aria-label beyond its placeholder; add one if your placeholder is not descriptive.
- Pair any visible trigger with a hint of the shortcut, such as a ⌘K kbd, so keyboard users discover it.