ui/components/command-palette

Command Palette

Terminal-styled command palette with built-in search filtering, grouped items, and keyboard navigation. Uses native dialog element with backdrop blur. Two orthogonal visual axes on Content (frame and density) keep visual chrome configurable without touching internals.

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Button } from "@/components/ui/button";5 import { CommandPalette } from "@/components/ui/command-palette";6 7 export default function CommandPaletteDemo() {8   const [open, setOpen] = useState(false);9 10   return (11     <div>12       <Button onClick={() => setOpen(true)}>Open Command Palette</Button>13       <CommandPalette open={open} onOpenChange={setOpen}>14         <CommandPalette.Content>15           <CommandPalette.Input placeholder="Type a command or search…" />16           <CommandPalette.List>17             <CommandPalette.Empty>No matching commands.</CommandPalette.Empty>18             <CommandPalette.Group heading="Suggested">19               <CommandPalette.Item id="history" value="Go to History">20                 Go to History21               </CommandPalette.Item>22               <CommandPalette.Item id="theme" value="Switch Theme" shortcut="⌘T">23                 Switch Theme24               </CommandPalette.Item>25               <CommandPalette.Item id="export" value="Export PDF">26                 Export PDF27               </CommandPalette.Item>28             </CommandPalette.Group>29             <CommandPalette.Group heading="System">30               <CommandPalette.Item id="settings" value="Settings Hub" shortcut=",">31                 Settings Hub32               </CommandPalette.Item>33               <CommandPalette.Item id="diagnostics" value="Run Diagnostics">34                 Run Diagnostics35               </CommandPalette.Item>36               <CommandPalette.Item id="logout" value="Log Out">37                 Log Out38               </CommandPalette.Item>39             </CommandPalette.Group>40           </CommandPalette.List>41           {/* Childless: the footer renders the canonical Navigate / Select /42               Close legend through the shared OverlayHints primitive. */}43           <CommandPalette.Footer />44         </CommandPalette.Content>45       </CommandPalette>46     </div>47   );48 }49

Installation

$pnpm exec dgadd add ui/command-palette

[Installs to]src/components/ui/command-palette[Item]ui/command-palette

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 "use client";2 3 import { useState } from "react";4 import { Button } from "@/components/ui/button";5 import { CommandPalette } from "@/components/ui/command-palette";6 7 export default function CommandPaletteDemo() {8   const [open, setOpen] = useState(false);9 10   return (11     <div>12       <Button onClick={() => setOpen(true)}>Open Command Palette</Button>13       <CommandPalette open={open} onOpenChange={setOpen}>14         <CommandPalette.Content>15           <CommandPalette.Input placeholder="Type a command or search…" />16           <CommandPalette.List>17             <CommandPalette.Empty>No matching commands.</CommandPalette.Empty>18             <CommandPalette.Group heading="Suggested">19               <CommandPalette.Item id="history" value="Go to History">20                 Go to History21               </CommandPalette.Item>22               <CommandPalette.Item id="theme" value="Switch Theme" shortcut="⌘T">23                 Switch Theme24               </CommandPalette.Item>25               <CommandPalette.Item id="export" value="Export PDF">26                 Export PDF27               </CommandPalette.Item>28             </CommandPalette.Group>29             <CommandPalette.Group heading="System">30               <CommandPalette.Item id="settings" value="Settings Hub" shortcut=",">31                 Settings Hub32               </CommandPalette.Item>33               <CommandPalette.Item id="diagnostics" value="Run Diagnostics">34                 Run Diagnostics35               </CommandPalette.Item>36               <CommandPalette.Item id="logout" value="Log Out">37                 Log Out38               </CommandPalette.Item>39             </CommandPalette.Group>40           </CommandPalette.List>41           {/* Childless: the footer renders the canonical Navigate / Select /42               Close legend through the shared OverlayHints primitive. */}43           <CommandPalette.Footer />44         </CommandPalette.Content>45       </CommandPalette>46     </div>47   );48 }49

Examples

Viewfinder frame

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Button } from "@/components/ui/button";5 import { CommandPalette } from "@/components/ui/command-palette";6 7 export default function CommandPaletteViewfinder() {8   const [open, setOpen] = useState(true);9 10   return (11     <>12       {!open ? (13         <Button type="button" onClick={() => setOpen(true)}>14           Show palette15         </Button>16       ) : null}17       <CommandPalette open={open} onOpenChange={setOpen}>18         <CommandPalette.Content modal={false} label="Viewfinder palette" frame="viewfinder">19           <CommandPalette.Input placeholder="Type a command…" />20           <CommandPalette.List>21             <CommandPalette.Empty>No matching commands.</CommandPalette.Empty>22             <CommandPalette.Group heading="Suggested">23               <CommandPalette.Item id="history" value="Go to History">24                 Go to History25               </CommandPalette.Item>26               <CommandPalette.Item id="theme" value="Switch Theme" shortcut="⌘T">27                 Switch Theme28               </CommandPalette.Item>29               <CommandPalette.Item id="export" value="Export PDF">30                 Export PDF31               </CommandPalette.Item>32             </CommandPalette.Group>33           </CommandPalette.List>34         </CommandPalette.Content>35       </CommandPalette>36     </>37   );38 }39

Terminal frame

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Button } from "@/components/ui/button";5 import { CommandPalette } from "@/components/ui/command-palette";6 7 export default function CommandPaletteTerminal() {8   const [open, setOpen] = useState(true);9 10   return (11     <>12       {!open ? (13         <Button type="button" onClick={() => setOpen(true)}>14           Show palette15         </Button>16       ) : null}17       <CommandPalette open={open} onOpenChange={setOpen}>18         <CommandPalette.Content modal={false} label="Terminal palette" frame="terminal">19           <CommandPalette.Input placeholder="Type a command…" />20           <CommandPalette.List>21             <CommandPalette.Empty>No matching commands.</CommandPalette.Empty>22             <CommandPalette.Group heading="Suggested">23               <CommandPalette.Item id="history" value="Go to History">24                 Go to History25               </CommandPalette.Item>26               <CommandPalette.Item id="theme" value="Switch Theme" shortcut="⌘T">27                 Switch Theme28               </CommandPalette.Item>29               <CommandPalette.Item id="export" value="Export PDF">30                 Export PDF31               </CommandPalette.Item>32             </CommandPalette.Group>33             <CommandPalette.Group heading="System">34               <CommandPalette.Item id="settings" value="Settings Hub" shortcut=",">35                 Settings Hub36               </CommandPalette.Item>37               <CommandPalette.Item id="logout" value="Log Out">38                 Log Out39               </CommandPalette.Item>40             </CommandPalette.Group>41           </CommandPalette.List>42         </CommandPalette.Content>43       </CommandPalette>44     </>45   );46 }47

Comfortable density

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Button } from "@/components/ui/button";5 import { CommandPalette } from "@/components/ui/command-palette";6 7 function SearchIcon() {8   return (9     <svg10       aria-hidden="true"11       width="16"12       height="16"13       viewBox="0 0 24 24"14       fill="none"15       stroke="currentColor"16       strokeWidth="2"17       strokeLinecap="round"18       strokeLinejoin="round"19       style={{ opacity: 0.6, flexShrink: 0 }}20     >21       <circle cx="11" cy="11" r="7" />22       <path d="m20 20-3-3" />23     </svg>24   );25 }26 27 export default function CommandPaletteComfortable() {28   const [open, setOpen] = useState(true);29 30   return (31     <>32       {!open ? (33         <Button type="button" onClick={() => setOpen(true)}>34           Show palette35         </Button>36       ) : null}37       <CommandPalette open={open} onOpenChange={setOpen}>38         <CommandPalette.Content39           modal={false}40           label="Comfortable palette"41           frame="card"42           density="comfortable"43         >44           <CommandPalette.Input45             placeholder="Search commands, files, settings…"46             prefix={<SearchIcon />}47           />48           <CommandPalette.List>49             <CommandPalette.Empty>No matching commands.</CommandPalette.Empty>50             <CommandPalette.Group heading="Workspace">51               <CommandPalette.Item id="search" value="Search files">52                 Search files53               </CommandPalette.Item>54               <CommandPalette.Item id="branch" value="Switch branch" shortcut="⌘B">55                 Switch branch56               </CommandPalette.Item>57               <CommandPalette.Item id="commits" value="View commits">58                 View commits59               </CommandPalette.Item>60             </CommandPalette.Group>61           </CommandPalette.List>62         </CommandPalette.Content>63       </CommandPalette>64     </>65   );66 }67

Dense density

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Button } from "@/components/ui/button";5 import { CommandPalette } from "@/components/ui/command-palette";6 7 export default function CommandPaletteDense() {8   const [open, setOpen] = useState(true);9 10   return (11     <>12       {!open ? (13         <Button type="button" onClick={() => setOpen(true)}>14           Show palette15         </Button>16       ) : null}17       <CommandPalette open={open} onOpenChange={setOpen}>18         <CommandPalette.Content modal={false} label="Dense palette" density="dense">19           <CommandPalette.Input placeholder="Type a command…" />20           <CommandPalette.List>21             <CommandPalette.Empty>No matching commands.</CommandPalette.Empty>22             <CommandPalette.Group heading="File">23               <CommandPalette.Item id="new-file" value="New file" shortcut="⌘N">24                 New file25               </CommandPalette.Item>26               <CommandPalette.Item id="save" value="Save" shortcut="⌘S">27                 Save28               </CommandPalette.Item>29               <CommandPalette.Item id="close" value="Close tab" shortcut="⌘W">30                 Close tab31               </CommandPalette.Item>32               <CommandPalette.Item id="reload" value="Reload" shortcut="⌘R">33                 Reload34               </CommandPalette.Item>35             </CommandPalette.Group>36             <CommandPalette.Group heading="View">37               <CommandPalette.Item id="toggle-sidebar" value="Toggle sidebar" shortcut="⌘\\">38                 Toggle sidebar39               </CommandPalette.Item>40               <CommandPalette.Item id="toggle-terminal" value="Toggle terminal" shortcut="⌃`">41                 Toggle terminal42               </CommandPalette.Item>43               <CommandPalette.Item id="zen" value="Zen mode">44                 Zen mode45               </CommandPalette.Item>46             </CommandPalette.Group>47           </CommandPalette.List>48         </CommandPalette.Content>49       </CommandPalette>50     </>51   );52 }53

Tones (manual)

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Button } from "@/components/ui/button";5 import { CommandPalette } from "@/components/ui/command-palette";6 7 export default function CommandPaletteTones() {8   const [open, setOpen] = useState(true);9 10   return (11     <>12       {!open ? (13         <Button type="button" onClick={() => setOpen(true)}>14           Show palette15         </Button>16       ) : null}17       <CommandPalette open={open} onOpenChange={setOpen}>18         <CommandPalette.Content modal={false} label="Toned palette">19           <CommandPalette.Input placeholder="Type a command…" />20           <CommandPalette.List>21             <CommandPalette.Empty>No matching commands.</CommandPalette.Empty>22             <CommandPalette.Group heading="Navigation">23               <CommandPalette.Item id="history" value="Go to History" tone="nav">24                 Go to History25               </CommandPalette.Item>26               <CommandPalette.Item id="branch" value="Switch Branch" tone="nav">27                 Switch Branch28               </CommandPalette.Item>29             </CommandPalette.Group>30             <CommandPalette.Group heading="Actions">31               <CommandPalette.Item id="export" value="Export PDF" tone="action">32                 Export PDF33               </CommandPalette.Item>34               <CommandPalette.Item id="deploy" value="Deploy preview" tone="action">35                 Deploy preview36               </CommandPalette.Item>37             </CommandPalette.Group>38             <CommandPalette.Group heading="AI">39               <CommandPalette.Item id="explain" value="Ask the assistant" tone="ai">40                 Ask the assistant41               </CommandPalette.Item>42               <CommandPalette.Item id="summary" value="Summarize diff" tone="ai">43                 Summarize diff44               </CommandPalette.Item>45             </CommandPalette.Group>46             <CommandPalette.Group heading="Danger">47               <CommandPalette.Item id="reset" value="Reset workspace" tone="destructive">48                 Reset workspace49               </CommandPalette.Item>50               <CommandPalette.Item id="logout" value="Log out" tone="destructive">51                 Log out52               </CommandPalette.Item>53             </CommandPalette.Group>54           </CommandPalette.List>55         </CommandPalette.Content>56       </CommandPalette>57     </>58   );59 }60

Tones (auto-coloring)

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Button } from "@/components/ui/button";5 import { CommandPalette } from "@/components/ui/command-palette";6 import { CommandPaletteHighlightItem } from "@/components/ui/command-palette/highlight";7 8 export default function CommandPaletteAutoTones() {9   const [open, setOpen] = useState(true);10 11   return (12     <>13       {!open ? (14         <Button type="button" onClick={() => setOpen(true)}>15           Show palette16         </Button>17       ) : null}18       <CommandPalette open={open} onOpenChange={setOpen}>19         <CommandPalette.Content modal={false} label="Auto-toned palette">20           <CommandPalette.Input placeholder="Type to filter & highlight…" />21           <CommandPalette.List>22             <CommandPalette.Empty>No matching commands.</CommandPalette.Empty>23             <CommandPalette.Group heading="Suggestions">24               <CommandPaletteHighlightItem id="go-history">25                 Go to History26               </CommandPaletteHighlightItem>27               <CommandPaletteHighlightItem id="open-settings">28                 Open Settings29               </CommandPaletteHighlightItem>30               <CommandPaletteHighlightItem id="run-tests">Run tests</CommandPaletteHighlightItem>31               <CommandPaletteHighlightItem id="deploy-prod">32                 Deploy production33               </CommandPaletteHighlightItem>34               <CommandPaletteHighlightItem id="ask-ai">35                 Ask the assistant36               </CommandPaletteHighlightItem>37               <CommandPaletteHighlightItem id="toggle-theme">38                 Toggle theme39               </CommandPaletteHighlightItem>40               <CommandPaletteHighlightItem id="delete-branch">41                 Delete branch42               </CommandPaletteHighlightItem>43               <CommandPaletteHighlightItem id="logout">Log out</CommandPaletteHighlightItem>44             </CommandPalette.Group>45           </CommandPalette.List>46         </CommandPalette.Content>47       </CommandPalette>48     </>49   );50 }51

Empty state

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Button } from "@/components/ui/button";5 import { CommandPalette } from "@/components/ui/command-palette";6 7 /**8  * The empty state, pinned open with a search value that matches nothing so the9  * fallback copy is visible without typing.10  */11 export default function CommandPaletteEmpty() {12   const [open, setOpen] = useState(true);13 14   return (15     <>16       {!open ? (17         <Button type="button" onClick={() => setOpen(true)}>18           Show palette19         </Button>20       ) : null}21       <CommandPalette open={open} onOpenChange={setOpen} search="qqq">22         <CommandPalette.Content modal={false} label="Empty palette">23           <CommandPalette.Input placeholder="Type a command…" />24           <CommandPalette.List>25             <CommandPalette.Empty>No matching commands.</CommandPalette.Empty>26             <CommandPalette.Group heading="Suggested">27               <CommandPalette.Item id="history" value="Go to History">28                 Go to History29               </CommandPalette.Item>30               <CommandPalette.Item id="theme" value="Switch Theme" shortcut="⌘T">31                 Switch Theme32               </CommandPalette.Item>33             </CommandPalette.Group>34           </CommandPalette.List>35         </CommandPalette.Content>36       </CommandPalette>37     </>38   );39 }40

API Reference

CommandPalette

Name	Type	Default	Description
open	boolean	false	Controlled open state. Required to actually show the palette — wire a trigger button or shortcut to setOpen(true).
onOpenChange	(open: boolean) => void	—	Called whenever open state changes.
search	string	—	Controlled search query.
onSearchChange	(value: string) => void	—	Called when the search query changes.
highlighted	string \| null	—	Controlled highlighted item id.
onHighlightChange	(id: string \| null) => void	—	Called when the highlighted item changes.
onActivate	(id: string) => void	—	Called when an item is activated (Enter or click). Fires after the item's own onSelect.
shouldFilter	boolean	true	Auto-filter items by search. Pass false to handle filtering yourself (e.g. server-side).
filter	(value: string, search: string) => boolean	—	Custom filter function. Defaults to case-insensitive substring match on the item's value (or id).

CommandPaletteContent

Name	Type	Default	Description
size	"sm" \| "md" \| "lg"	"md"	Modal width preset.
frame	"border" \| "viewfinder" \| "terminal" \| "card" \| "none"	"border"	Shell chrome style. "border" renders a 1px hairline. "viewfinder" renders four corner brackets with no border plus a 2px left accent bar on the selected row. "terminal" renders top + bottom 2px rules with inverted selection and swaps the default prefix glyph from > to $. "card" renders an 8px rounded shell with a subtle gradient surface and a floating rounded selection (compose with a search-icon `prefix` for the Linear look). "none" is a bare shell for embedding.
density	"compact" \| "comfortable" \| "dense"	"compact"	Typographic and spacing surface. Switches a token block (--command-palette-row-h, --command-palette-input-py, --command-palette-list-p, --command-palette-text-size, etc.) consumed by every inner slot via [data-density] selectors in command-palette/command-palette.css. "compact" matches the V1 refined-mono target, "comfortable" is Linear-ish breathing room, "dense" is VSCode-tight.
modal	boolean	true	Renders the palette as a modal dialog in the browser top layer (default). Pass false to render it in the document flow instead - an embedded palette with the same frame, density, and highlight chrome, without a backdrop, focus trap, or focus restoration. Inline palettes still honour open, so they unmount when the consumer closes them.
label	string	"Command palette"	Accessible name for the palette. Applied to the modal dialog, or to the embedded region when modal is false.

CommandPaletteItem

Name	Type	Default	Description
idrequired	string	—	Stable unique id used for highlight state and aria-activedescendant.
value	string	—	Searchable text. Defaults to id when omitted.
icon	ReactNode	—	Optional leading icon. Inherits tone color when a non-neutral tone is set.
shortcut	string	—	Keyboard shortcut hint rendered next to the label.
tone	"neutral" \| "nav" \| "action" \| "settings" \| "destructive" \| "ai"	"neutral"	Semantic tone. Renders a 2px left bar and tints the optional icon via [data-tone] selectors. The label color stays inherited so contrast holds under any frame. Map: nav→info, action→success, settings→warning, destructive→destructive, ai→accent.
onSelect	() => void	—	Called when the item is activated. Runs before CommandPalette.onActivate.
disabled	boolean	false	Disable activation and skip in keyboard navigation.

CommandPaletteGroup

Name	Type	Default	Description
heading	ReactNode	—	Group heading rendered above the items.

CommandPaletteInput

Name	Type	Default	Description
label	string	"Command search"	Accessible label for the search input.
placeholder	string	"Type a command…"	Search input placeholder.
prefix	ReactNode	—	Optional leading content. When omitted, a CSS-driven glyph from --command-palette-prefix-content is rendered (default ">"; terminal frame swaps to "$").
suffix	ReactNode	—	Optional trailing content. Defaults to the CommandPaletteCount readout plus an Esc close button; supplying your own suffix replaces both.
closeLabel	string	"Close"	Accessible name for the default Esc close control — the palette's only touch-reachable close affordance. Set it to localize that name.

Data attributes

Attribute	Applies to	Values	Description
data-state	CommandPaletteContent	"open" \| "closed"	Native dialog open state mirrored by the shared shell. Embedded palettes emit "open" while mounted.
data-frame	CommandPaletteContent	"border" \| "viewfinder" \| "terminal" \| "card" \| "none"	Shell chrome variant.
data-density	CommandPaletteContent	"compact" \| "comfortable" \| "dense"	Typographic and spacing density.
data-value	CommandPaletteItem	item id	Stable id used for filtering, highlight, and activation.
data-highlighted	CommandPaletteItem	present when highlighted	Marks the active descendant. All highlight styling keys off this attribute; aria-selected stays for listbox semantics.
data-tone	CommandPaletteItem	"neutral" \| "nav" \| "action" \| "settings" \| "destructive" \| "ai"	Semantic tone for the optional accent bar and icon tint.
data-empty	CommandPaletteCount	present when the filter matched nothing	Switches the readout to the error colour alongside CommandPaletteEmpty.

Accessibility

Keyboard Navigation

Arrow keys navigate items (with wrapping), Enter activates the highlighted item. Home and End retain their native search-input editing behavior and do not move the highlight. Escape clears search first, then closes the palette. Hovering (mousemove) over an item also moves the highlight, so mouse and keyboard share a single selection model. Navigation is handled internally via @diffgazer/keys's useNavigation hook.

Key	Action
ArrowUp / ArrowDown	Moves highlight through enabled visible items.
Enter	Activates the highlighted item.
Escape	Clears the search query first, then closes the palette.

Keyboard navigation

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Button } from "@/components/ui/button";5 import { CommandPalette } from "@/components/ui/command-palette";6 7 export default function CommandPaletteDemo() {8   const [open, setOpen] = useState(false);9 10   return (11     <div>12       <Button onClick={() => setOpen(true)}>Open Command Palette</Button>13       <CommandPalette open={open} onOpenChange={setOpen}>14         <CommandPalette.Content>15           <CommandPalette.Input placeholder="Type a command or search…" />16           <CommandPalette.List>17             <CommandPalette.Empty>No matching commands.</CommandPalette.Empty>18             <CommandPalette.Group heading="Suggested">19               <CommandPalette.Item id="history" value="Go to History">20                 Go to History21               </CommandPalette.Item>22               <CommandPalette.Item id="theme" value="Switch Theme" shortcut="⌘T">23                 Switch Theme24               </CommandPalette.Item>25               <CommandPalette.Item id="export" value="Export PDF">26                 Export PDF27               </CommandPalette.Item>28             </CommandPalette.Group>29             <CommandPalette.Group heading="System">30               <CommandPalette.Item id="settings" value="Settings Hub" shortcut=",">31                 Settings Hub32               </CommandPalette.Item>33               <CommandPalette.Item id="diagnostics" value="Run Diagnostics">34                 Run Diagnostics35               </CommandPalette.Item>36               <CommandPalette.Item id="logout" value="Log Out">37                 Log Out38               </CommandPalette.Item>39             </CommandPalette.Group>40           </CommandPalette.List>41           {/* Childless: the footer renders the canonical Navigate / Select /42               Close legend through the shared OverlayHints primitive. */}43           <CommandPalette.Footer />44         </CommandPalette.Content>45       </CommandPalette>46     </div>47   );48 }49

Notes

Requires @diffgazer/keys (package mode)

CommandPalette's arrow-key navigation and focus restoration import from the required @diffgazer/keys peer. Package consumers must install @diffgazer/keys with @diffgazer/ui; packages are not yet published to npm, so until the first release install both from locally packed tarballs. Importing @diffgazer/ui/components/command-palette without keys fails at module load with an error naming the missing @diffgazer/keys package. Copy/dgadd consumers do not need the package — copy mode rewrites the keyboard hooks to local source.

Controlled Open State

CommandPalette is opened from outside via open/onOpenChange. Wire a trigger button (or a global keyboard shortcut) to setOpen(true). Search and highlight state can also be controlled via search/onSearchChange and highlighted/onHighlightChange, or left uncontrolled.

Built-in Filtering

Items are filtered automatically as you type. Each item matches against its `value` prop (falls back to `id`). Pass `shouldFilter={false}` to disable and handle filtering yourself. Pass a custom `filter` function to override the default case-insensitive includes match. Filtering uses the live search value, including the controlled `search` prop when provided.

Composition Contract

Use CommandPalette.Item as an explicit child in the CommandPalette JSX tree, usually inside CommandPalette.List or CommandPalette.Group. Custom item UI belongs inside CommandPalette.Item. Components that create items internally from an opaque wrapper are not part of the current public contract.

Built-in Keyboard Navigation

CommandPalette integrates @diffgazer/keys's useNavigation internally for arrow-key navigation, wrapping, and Enter activation. Hover (mousemove) and keyboard selection share the same highlighted state, so mousing over an item moves the cmdk-style cursor. Highlight and search state can be controlled externally via highlighted/onHighlightChange and search/onSearchChange.

Variants & Density

CommandPaletteContent exposes two orthogonal axes. `frame` picks the shell chrome — "border" (1px hairline, default), "viewfinder" (no border, four corner brackets + 2px left accent bar on selection), "terminal" (top + bottom 2px rules, inverted selection, prefix glyph becomes $), "card" (rounded 8px shell with a subtle gradient surface and floating rounded selection — Linear-ish), or "none" (bare shell for embedding). `density` picks the typographic & spacing surface — "compact" (default), "comfortable", or "dense". Both are plain TypeScript types (CommandPaletteFrame, CommandPaletteDensity) whose visual styling is driven by [data-frame] / [data-density] selectors in command-palette/command-palette.css, so consumers can override token values per-instance via CSS custom properties.

Modal or Embedded

By default Content renders a native modal dialog in the browser top layer with a focus trap and focus restoration. Pass modal={false} to embed the same surface in the page: identical frame, density, tone, and highlight chrome, but in the document flow, without a backdrop and without stealing focus - useful for a persistent search pane, and for documenting the open surface itself. The examples below are embedded palettes for exactly that reason.

Keyboard legend

CommandPaletteFooter renders the shared OverlayHints primitive (registry/ui/shared/overlay-hints) when given no children: Navigate / Select / Close, in one layout every keyboard-first overlay in the library speaks. Pass children to take full control. The legend is aria-hidden — the shortcuts are already reachable through the real controls — and at coarse pointer every hint that is not marked touch-relevant is hidden, collapsing the whole bar rather than leaving an empty strip; on a 390-wide palette that recovers a full row, and the working close affordance is the Esc button in the input row.

Narrow-viewport geometry

Below 640px the panel insets 12px from each viewport edge (max-sm:mx-3 plus a matching width) so both vertical hairlines and the offset shadow stay on-screen instead of being clipped. The panel is top-pinned at every width — margin-block-start: max(12px, env(safe-area-inset-top)) with an auto bottom margin — so the software keyboard shrinking the visual viewport cannot displace the input row mid-typing. The height cap stays max-h-[80dvh]. The footer pads past the home indicator with env(safe-area-inset-bottom), which needs viewport-fit=cover on the host page and degrades to the base padding without it. The Esc affordance in the input row is a real button with the accessible name "Close" and a 44x44 hit area expanded via ::before, so touch users have a working close control; the visible chip does not move.

Position readout

The default input suffix renders CommandPaletteCount: a bracketed readout of the highlighted position over the filtered total — [3/24] with a highlight, [24] without one, and [0] with a data-empty marker (error colour) when the filter matched nothing. It is aria-hidden, because the palette's existing polite live region already announces the result count; rendering it visibly is what closes the gap for sighted keyboard users. Supplying your own `suffix` replaces it, so compose CommandPalette.Count yourself if you want both.

Optional auto-coloring

Items accept a `tone` prop ("neutral" | "nav" | "action" | "settings" | "destructive" | "ai") that renders a 2px left accent bar and tints the optional icon. The label color is unchanged so contrast remains readable, including under the terminal frame's inverted selection. For automatic classification + inline match highlighting, import `CommandPaletteHighlightItem` from `@diffgazer/ui/components/command-palette/highlight`. It infers tone from a small regex table (verbs like "delete", "go to", "toggle", "ask", "run") and wraps matched characters in `<mark data-slot="command-palette-item-match">`.

Source

Install via CLI: pnpm exec dgadd add ui/command-palette. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Command Palette

Installation

Usage

Examples

Viewfinder frame

Terminal frame

Comfortable density

Dense density

Tones (manual)

Tones (auto-coloring)

Empty state

API Reference

CommandPalette

CommandPaletteContent

CommandPaletteItem

CommandPaletteGroup

CommandPaletteInput

Data attributes

Accessibility

Keyboard Navigation

Keyboard navigation

Notes

Requires @diffgazer/keys (package mode)

Controlled Open State

Built-in Filtering

Composition Contract

Built-in Keyboard Navigation

Variants & Density

Modal or Embedded

Keyboard legend

Narrow-viewport geometry

Position readout

Optional auto-coloring

Source

View component source (54 files)