CommandPalette

A ⌘K command palette: a top-anchored overlay with a search field over a grouped, keyboard-navigable command list. It renders its own portal rather than building on Modal, which centres its panel, focuses the dialog element instead of an input, forces body padding, and pins an inline max-height — none of which a palette can override. The stacking primitives are shared though (useModalStack, useEscapeLayer, the zIndex scale), so a palette opened over a modal sits above it and Escape still dismisses exactly one layer.

Source

Import

import { CommandPalette } from "@flanksource/clicky-ui/components";

Demos

Default · Open in Storybook

Hotkey Opens · Open in Storybook

Filter And Run · Open in Storybook

The props table documents the component-specific surface. Standard DOM attributes inherited from React, such as className, event handlers, and accessibility attributes, may also be accepted when the component’s prop type extends a native element.

Props

Prop	Type	Default	Description
ariaLabel	string	Command palette	Accessible name for the dialog. Defaults to "Command palette".
className	string	—	Classes applied to the palette panel.
closeOnSelect	boolean	true	Close after a successful activation. Defaults to true.
customInput	ReactNode	—	Replaces the built-in search field while preserving the palette and result list.
emptyState	ReactNode	—	Replaces the default "No results" body.
filter	false | CommandFilter	—	How rows are matched. Defaults to a case-insensitive substring match over label, description and keywords, ranked by hit position. Pass `false` when the caller already filtered `groups` server-side.
focusListKey	number	—	Changing this value focuses the result list for keyboard selection.
footer	ReactNode	—	Non-interactive hint strip pinned below the list.
groups*	CommandGroup[]	—	Command groups, rendered top to bottom in array order.
hotkey	string | null	mod+k	Global shortcut that opens (and, while open, closes) the palette, in `useHotkey` syntax — `"mod+k"` by default, where `mod` is ⌘ on macOS and Ctrl elsewhere. Pass `null` when an ancestor owns the binding.
listMaxHeight	string | number	min(24rem, 50dvh)	Max height of the scrolling list. Defaults to "min(24rem, 50dvh)". Inline style.
loading	boolean	—	Shows a loading row instead of the empty state while results are in flight.
onOpenChange	(…) => void	—	Called with the next open state on hotkey, Escape, backdrop click, and selection.
onQueryChange	(…) => void	—	Called with the next query on every keystroke. Required for server-side search.
onSelect	(…) => void	—	Fallback handler for items with no own `onSelect`.
open	boolean	—	Controls visibility. Omit to run uncontrolled — the palette then owns its open state and the built-in hotkey works with no wiring beyond mounting it.
placeholder	string	Type a command or search…	Ghost text in the search input. Defaults to "Type a command or search…".
query	string	—	Controlled query. Omit to let the palette own the input.
resetQueryOnClose	boolean	true	Clear the query when the palette closes. Defaults to true.
size	enum	md	Panel width preset. Defaults to "md".
topOffset	string | number	12vh	Distance from the viewport top. Defaults to "12vh". Applied as an inline style.