useCommandPalette

Manages command palette state and command registration.

Signature

function useCommandPalette(
  options?: UseCommandPaletteOptions
): UseCommandPaletteReturn

Parameters

UseCommandPaletteOptions

Property	Type	Default	Description
initialCommands	Command[]	[]	Commands to register initially
enableShortcut	boolean	true	Enable Cmd/Ctrl+K shortcut
onExecute	(command: Command) => void	-	Called when command executes

Return Type

UseCommandPaletteReturn

Property	Type	Description
isOpen	boolean	Whether palette is open
commands	Command[]	All registered commands
groupedCommands	Map<string, Command[]>	Commands grouped by group property
open	() => void	Open the palette
close	() => void	Close the palette
toggle	() => void	Toggle open state
register	(commands: Command[]) => void	Replace all commands
add	(commands: Command[]) => void	Add commands (skips duplicates)
remove	(ids: string[]) => void	Remove commands by ID
clear	() => void	Remove all commands
execute	(id: string) => Promise<void>	Execute command by ID

Types

Command

Property	Type	Required	Description
id	string	Yes	Unique identifier
label	string	Yes	Display label
action	() => void | Promise<void>	Yes	Action to execute
keywords	string[]	No	Search keywords
icon	ReactNode	No	Icon element
group	string	No	Group name (default: 'Commands')
shortcut	string	No	Shortcut display text
disabled	boolean	No	Whether command is disabled

Example

const palette = useCommandPalette({
  initialCommands: [
    { id: 'home', label: 'Go Home', group: 'Navigation', action: () => navigate('/') },
  ],
})

palette.add([
  { id: 'settings', label: 'Settings', action: () => openSettings() },
])

<CommandPalette
  open={palette.isOpen}
  onOpenChange={(open) => open ? palette.open() : palette.close()}
  commands={palette.commands}
  groupedCommands={palette.groupedCommands}
  onSelect={(cmd) => palette.execute(cmd.id)}
/>

See also

• useCommandPalette (Conceptual)
• Command Palette Usage Pattern
• CommandPalette Component