# Command

> Source: https://design.nanatec.co.ke/components/command/
> A command palette: a search field over grouped pages and actions, opened from anywhere with ⌘K or Control+K.

The command palette lets people jump to a page or run an action by typing its name. It
opens in a dialog from anywhere on the page with ⌘K on Apple devices and Control+K
elsewhere, filters as they type, and closes once they choose. The palette also works on its
own, inside a page. For a short list of actions on one button, use a
[menu](/components/menu/); to pick a value for a form, use a
[combobox](/components/combobox/).

## Preview

## Installation

```html
<nana-command-dialog></nana-command-dialog>

<script type="module">
  const palette = document.querySelector('nana-command-dialog');
  palette.groups = [
    {
      heading: 'Pages',
      items: [{ id: '/claims', label: 'Claims', icon: 'document-text', keywords: ['motor'] }],
    },
    {
      heading: 'Actions',
      items: [{ id: 'new-claim', label: 'New claim', icon: 'plus', shortcut: 'mod+n' }],
    },
  ];
  palette.addEventListener('nana-select', (event) => console.log(event.detail.item.id));
</script>
```

Call `show()` to open it from a button as well. `<nana-command>` is the palette without the
dialog, for a page of its own. An icon is the name of a registered
[icon](/components/icon/).

## Shortcut

The dialog opens and closes on `mod+k`: ⌘K on Apple devices, Control+K elsewhere. Set
`shortcut` to another combination in the [kbd](/components/kbd/) format, such as
`mod+shift+p`, or turn it off with `shortcut={false}` in Svelte and `shortcut=""` on the
web component. It opens with the search field focused and empty each time.

The previews on this page use `mod+j`, because this site's own search already answers to
⌘K. Pick a combination nothing else on your page uses.

## Keyboard

| Key | Does |
| --- | --- |
| ⌘K or Control+K | Opens or closes the palette |
| Typing | Filters the commands |
| Up and Down arrows | Move through the commands, skipping disabled ones, and wrap around |
| Enter | Runs the highlighted command |
| Escape | Closes the palette |

## Accessibility

- The search field is a combobox over a listbox, named by `label`, "Commands" by default.
  Focus stays in the field; the highlighted command is announced as the active option.
- Each group is named by its heading. A disabled command stays in the list, announced as
  unavailable, and cannot be run.
- The message shown when nothing matches is a status, so it is announced as people type.
- A shortcut shown beside a command is hidden from screen readers; put what it does in the
  label.

## API

`groups` is required on both. Bind `query` on `NanaCommand` to read or set the search.
