All components (204)

Command palette

Layers · CommandPalette · .amset-palette

What it is and when to use it

The command palette, the classic Ctrl+K: it opens with the keyboard from anywhere, you type and jump wherever you want. Inside it is a modal dialog with a search field and the list of results in groups.

When to use it

An application with many screens or repeated actions: go to orders, create a customer, import.
aliases on a command for the words that should also find it: they enter the search but are not drawn.
shortcut on each command to show its key (it is informative: it does nothing by itself).
shortcut={null} on the palette if only its consumer opens it, with open and onOpenChange, without Ctrl+K.

When not to

Choosing a value from a long list inside a form, typing to filter: SearchField.
The actions of a row or a button: ActionMenu.

Keyboard: Ctrl+K or Cmd+K opens it from anywhere, even with focus in a text field; the key is changed with the palette's shortcut. On opening, focus goes to the search field. Typing filters; Up Arrow and Down Arrow move through the results without leaving the field, skipping the disabled ones and without wrapping around; Enter chooses and closes. Escape closes. When it closes, what was typed is forgotten.

Accessibility: the dialog and the field are named with title ("Search and jump"), the list is named "Results" and each group carries its title. Focus never leaves the field: the highlighted row is announced with aria-activedescendant, and how many results remain is announced in a live region. Icons are decoration. A command with disabled is seen and cannot be chosen. If nothing matches, it says so (noResultsMessage).

Fine-tuning: CSS variables --amset-palette-width (28, 36 or 44 rem depending on the size), --amset-palette-height and --amset-palette-radius. The palette is the browser's <dialog> —the veil is its ::backdrop— and it is attached to the top, because centered vertically it ends up too low on a tall screen.

What it looks like

<CommandPalette
  groups={[{ key: 'ir', title: 'Go to', commands: [
    { key: 'orders', label: 'Orders', description: 'All orders' },
  ] }]}
  open={abierta}
  onOpenChange={setAbierta}
  shortcut={null}
  onSelect={ir}
/>

Props

Import it with import { CommandPalette } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`groups`required	`readonly CommandGroup[]`	—
`onSelect`required	`(key: string) => void`	—
`className`	`string`	Merged with the library classes; it does not replace them.
`footer`	`ReactNode`	Footer with the key cheat sheet.
`noResultsMessage`	`string`	—
`onOpenChange`	`(open: boolean) => void`	—
`open`	`boolean`	—
`placeholder`	`string`	—
`shortcut`	`string \| null`	Shortcut that opens it, in the `KeyboardEvent.key` format together with Ctrl or Cmd. `null` leaves it without its own shortcut (whoever uses it opens it).
`size`	`"sm" \| "md" \| "lg"`	The width of the palette: 28, 36 or 44 rem.
`title`	`string`	—

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

CSS variables

These CSS variables are how you adapt it. Declare them on the component's selector, not on :root: the stylesheet redeclares them in the rule itself, and a declaration on the same element always wins.

Variable	Default
`--amset-palette-width`	`36rem`
`--amset-palette-height`	`28rem`
`--amset-palette-radius`	`var(--amset-radius-lg)`

How to change it

.amset-palette {
  --amset-palette-width: ...;
  --amset-palette-height: ...;
}

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: