CommandPalette

A searchable command UI for fast actions (similar to “Command Palette” in editors).

Usage

ui.commandPalette({
  id: "palette",
  open: state.open,
  query: state.query,
  placeholder: "Search files and commands...",
  maxVisible: 8,
  loading: state.commandsLoading,
  sources: [
    {
      id: "cmd",
      name: "Commands",
      prefix: ">",
      getItems: (q) => getCommandItems(q),
    },
  ],
  selectedIndex: state.selectedIndex,
  onChange: (q) => app.update((s) => ({ ...s, query: q })),
  onSelectionChange: (i) => app.update((s) => ({ ...s, selectedIndex: i })),
  onSelect: (item) => runCommand(item.id),
  onClose: () => app.update((s) => ({ ...s, open: false })),
})

Props

Prop	Type	Default	Description
`id`	`string`	required	Widget identifier.
`open`	`boolean`	required	Whether the palette is visible.
`query`	`string`	required	Current search query.
`sources`	`CommandSource[]`	required	Command providers used to produce results.
`selectedIndex`	`number`	required	Currently highlighted result index.
`loading`	`boolean`	`false`	Shows a loading indicator in the input area. Async `getItems` fetches also set loading internally while pending.
`placeholder`	`string`	`"Search commands..."`	Text shown when `query` is empty. Keep it short so the input stays readable on narrow terminals.
`maxVisible`	`number`	`10`	Maximum visible result rows. Useful for capping palette height in smaller viewports.
`width`	`number`	`60`	Palette width in cells (clamped to viewport width).
`frameStyle`	`{ background?, foreground?, border? }`	-	Optional frame/surface colors for palette background, text, and border.
`onChange`	`(query) => void`	required	Called when the query changes.
`onSelect`	`(item) => void`	required	Called when a result item is selected.
`onClose`	`() => void`	required	Called when the palette should close.
`onSelectionChange`	`(index) => void`	-	Called when highlighted index changes.
`focusConfig`	`FocusConfig`	-	Control focus visuals; `{ indicator: "none" }` suppresses focused item highlight

Notes

Command sources can be sync or async (getItems may return a Promise).
open, query, and selectedIndex are controlled props. Keep them in app state, update query from onChange, close state from onClose, and update selectedIndex from onSelectionChange when you want keyboard highlight changes to persist between frames.
maxVisible accepts non-negative values; 0 hides the results list while keeping the palette input visible.
Height is derived from maxVisible + 4 (frame + input + separator + list rows), then clamped to viewport height.
Palette x/y placement is clamped to the viewport (default y target is roughly one-third from top).
Enabled item shortcut values become active overlay shortcuts while this palette is open and topmost. Matching a shortcut calls onSelect(item) and then onClose().
Disabled items do not register shortcuts. If multiple enabled results in the active palette share one shortcut, the later result in the resolved item list wins.
Shortcut labels are display and routing metadata only; they are not used in palette filtering or ranking today.

Shortcut behavior

ui.commandPalette({
  id: "palette",
  open: state.open,
  query: state.query,
  sources: [
    {
      id: "commands",
      name: "Commands",
      getItems: () => [
        { id: "save", label: "Save File", shortcut: "Ctrl+S" },
        { id: "open", label: "Open File", shortcut: "Ctrl+O" },
      ],
    },
  ],
  selectedIndex: state.selectedIndex,
  onChange: (query) => app.update((s) => ({ ...s, query })),
  onSelectionChange: (selectedIndex) => app.update((s) => ({ ...s, selectedIndex })),
  onSelect: (item) => runCommand(item.id),
  onClose: () => app.update((s) => ({ ...s, open: false })),
})

When the palette is open, the shortcuts above are active automatically. Use app.keys() only for shortcuts that should continue to work when the palette is closed:

app.keys({
  "ctrl+s": () => runCommand("save"),
  "ctrl+o": () => runCommand("open"),
})

Next: Code editor.

CommandPalette

Usage

Props

Notes

Shortcut behavior

On this page