Command

The ⌘K palette — one overlay that searches everything, with a global shortcut it binds itself.

<Commandtrigger={<Button icon={IconSearch} iconEnd={<Command.Shortcut keys="mod+k" />}>Search</Button>}items={[  { value: "deploy", label: "Deploy acme-api", description: "Production", icon: IconRocket, group: "Actions" },  { value: "logs", label: "View logs", icon: IconList, group: "Actions" },  { value: "settings", label: "Project settings", icon: IconGear, group: "Navigate" },]}onSelect={(item) => run(item.value)}/>

The command palette: the overlay that lands near the top of the screen and searches everything at once.

It is deliberately not a dialog you happen to put an input in. It sits high rather than centred, so results grow downward into space you were already looking at; it opens on a global shortcut; and Escape is the only button it needs.

Usage

tsx

import { Command } from "@heyo-sh/heyo-ui";<Command items={commands} onSelect={(item) => run(item.value)} />;

Mount it once near the root. It binds ⌘K / Ctrl K itself — there is no provider, and no key handler for you to write.

Items

Every row is data. label and description are both matched against the query, keywords adds terms that match without being shown, and group sorts rows under a heading in first-seen order.

tsx

const items: CommandItem[] = [  {    value: "deploy",    label: "Deploy acme-api",    description: "Production · fra1",    icon: IconRocket,    shortcut: (      <Kbd.Group>        <Kbd>⌘</Kbd>        <Kbd>D</Kbd>      </Kbd.Group>    ),    keywords: ["ship", "release"],    group: "Actions",    onSelect: () => deploy(),  },];

An item's own onSelect runs first, then the palette's onSelect — one for the row, one for the "whatever was chosen" path.

Server-side search

Pass onQueryChange and the palette stops filtering: items is rendered exactly as given, so you can debounce, hit an API, and rank the results yourself. loading swaps the leading icon for a spinner while they are in flight.

tsx

<Command  items={results}  loading={isPending}  onQueryChange={(query) => startTransition(() => search(query))}/>

The trigger

trigger renders anything that opens the palette — usually a button in the header. Command.Shortcut spells a shortcut for the current platform, so the same markup shows ⌘K on macOS and Ctrl K everywhere else.

CtrlKCtrlShiftP

<Command.Shortcut keys="mod+k" /><Command.Shortcut keys="mod+shift+p" />

Inline search is a Combobox

Command is a global overlay. For a field with a dropdown of matches inside a form, reach for Combobox.

Properties

itemsCommandItem[]required

Everything the palette can find.

shortcutstring | falseoptional

The global shortcut that opens it. "mod+k" is ⌘K on macOS and Ctrl K elsewhere. It defaults to "mod+k"; pass false to bind it yourself.

triggerReactNodeoptional

Anything that opens the palette — a header button, a menu row.

open / defaultOpen / onOpenChangeboolean, fnoptional

Controlled and uncontrolled open state.

onSelect(item: CommandItem) => voidoptional

Fires for every chosen row, after the item's own onSelect.

onQueryChange(query: string) => voidoptional

Takes over filtering. When set, items is rendered exactly as given.

querystringoptional

The controlled query. Only needed alongside onQueryChange.

loadingbooleanoptional

Swaps the leading icon for a spinner while results are in flight.

placeholderstringoptional

Placeholder for the search field.

emptyMessageReactNodeoptional

Shown when nothing matches.

footerReactNode | falseoptional

Replaces the default ↑↓ / ↵ / esc legend. Pass false to drop the bar.

CommandItem

valuestringrequired

A stable id, handed back to onSelect.

labelstringrequired

The row's headline. Matched against the query.

descriptionReactNodeoptional

A second line — a path, an id, what the action does. Also matched.

iconIconLikeoptional

The leading glyph.

shortcutReactNodeoptional

A right-aligned hint, usually a Kbd.Group.

groupstringoptional

The section heading this row lives under.

keywordsstring[]optional

Extra terms to match on without showing them.

disabledbooleanoptional

Dims the row and ignores interaction.

onSelect() => voidoptional

Runs when the row is chosen, before the palette closes.

Command.Shortcut

keysstringrequired

A shortcut such as "mod+k", rendered as Kbd keys for this platform.

formatShortcut

tsx

import { formatShortcut } from "@heyo-sh/heyo-ui";formatShortcut("mod+k"); // ["⌘", "K"] on macOS, ["Ctrl", "K"] elsewhere

Loading documentation…