# `PetalComponents.Command`
[🔗](https://github.com/petalframework/petal_components/blob/v4.15.3/lib/petal_components/command.ex#L1)

A command palette — the ⌘K menu. Type to filter, arrow keys to move,
Enter to run. Items are real links and buttons, so `navigate`, `patch`
and any `phx-*` binding work exactly as they do everywhere else in
LiveView.

Filtering happens client-side in the `PetalCommand` hook (zero
dependencies), so keystrokes never wait on the server. Items are hidden,
never reordered — the server owns DOM order, which keeps the component
safe under LiveView patches.

Two shells:

  * `command/1` — an inline palette panel (for docs pages, sidebars,
    pickers).
  * `command_dialog/1` — the palette in a native `<dialog>`, opened with
    ⌘K / Ctrl+K (configurable) or `JS.dispatch("pc:command-open")`. The
    native element gives the top layer, focus trap, backdrop and Escape
    for free.

The markup follows the WAI-ARIA combobox pattern: the input carries
`role="combobox"` and `aria-activedescendant`, the list is a `listbox`,
items are `option`s. Keyboard focus never leaves the input; selection is
a virtual highlight.

# `command`

The inline command palette.

    <.command id="file-menu">
      <.command_input placeholder="Type a command or search..." />
      <.command_list>
        <.command_empty>No results found.</.command_empty>
        <.command_group heading="Suggestions">
          <.command_item navigate={~p"/calendar"}>
            <.icon name="hero-calendar" /> Calendar
          </.command_item>
          <.command_item phx-click="open_emoji">
            <.icon name="hero-face-smile" /> Search emoji
            <.command_shortcut>⌘E</.command_shortcut>
          </.command_item>
        </.command_group>
      </.command_list>
    </.command>

## Attributes

* `id` (`:string`) (required) - unique id; the PetalCommand hook mounts here.
* `loop` (`:boolean`) - arrow keys wrap from the last item to the first and back. Defaults to `false`.
* `class` (`:any`) - extra classes for the palette panel. Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block` (required)

# `command_dialog`

The command palette in a native `<dialog>` — the classic ⌘K experience.

    <.command_dialog id="cmdk">
      <.command_input placeholder="Type a command or search..." />
      <.command_list>
        <.command_empty>No results found.</.command_empty>
        ...
      </.command_list>
    </.command_dialog>

Open it from any element:

    <.button phx-click={PetalComponents.Command.open_command("cmdk")}>
      Search <.command_shortcut>⌘K</.command_shortcut>
    </.button>

The dialog closes on Escape, backdrop click, or after an item runs
(add `data-keep-open` to an item to opt out).

## Attributes

* `id` (`:string`) (required) - unique id for the dialog; open it with ⌘K or open_command/1.
* `shortcut` (`:string`) - the key bound with Cmd (mac) / Ctrl to toggle the dialog. Set to nil to disable the global binding. Defaults to `"k"`.
* `loop` (`:boolean`) - arrow keys wrap around the list. Defaults to `false`.
* `reset_on_close` (`:boolean`) - clear the query (and restore all items) when the dialog closes. Defaults to `true`.
* `class` (`:any`) - extra classes for the palette panel inside the dialog. Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block` (required)

# `command_empty`

Shown only when the query matches nothing.
## Attributes

* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block` (required)

# `command_group`

Groups related items. Hides itself when every item inside is filtered out.
## Attributes

* `heading` (`:string`) - group heading, rendered above the items. Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block` (required)

# `command_input`

The search field. Keyboard focus lives here; the list highlight is virtual.
## Attributes

* `placeholder` (`:string`) - Defaults to `"Type a command or search..."`.
* `autofocus` (`:boolean`) - focus the input on mount (dialogs focus it on open regardless). Defaults to `false`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `command_item`

One entry in the palette. A link when `navigate`/`patch`/`href` is set,
a button otherwise. `value` (plus `keywords`) is what typing matches;
it defaults to the item's visible text.

## Attributes

* `value` (`:string`) - the text the filter matches against. Defaults to the item's visible text. Defaults to `nil`.
* `keywords` (`:list`) - extra search aliases for this item. Defaults to `[]`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `navigate` (`:string`) - live_redirect target - renders the item as a link. Defaults to `nil`.
* `patch` (`:string`) - live_patch target - renders the item as a link. Defaults to `nil`.
* `href` (`:string`) - plain link target - renders the item as a link. Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted. phx-click and friends work here - Enter clicks the highlighted item. Supports all globals plus: `["target", "rel", "method", "download"]`.
## Slots

* `inner_block` (required)

# `command_list`

Scrollable container for groups and items.
## Attributes

* `label` (`:string`) - accessible name for the listbox. Defaults to `"Commands"`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block` (required)

# `command_separator`

A hairline between groups. Hidden automatically while a query is active.
## Attributes

* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `command_shortcut`

A right-aligned keyboard hint inside an item.
## Attributes

* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block` (required)

# `command_trigger`

The visible button that opens a `command_dialog` - the search pill every
⌘K app puts in its header, and its icon-only sibling for tight rows.

    <.command_trigger dialog_id="cmdk" label="Search docs…" />
    <.command_trigger dialog_id="cmdk" variant="icon" class="md:hidden" />

Wired through the `PetalCommandTrigger` hook rather than a `phx-click` JS
command on purpose: hooks mount on dead views (a LiveView 1.1 behaviour,
and 1.1 is the package's dependency floor), while phx-click JS commands
only execute inside a LiveView - and marketing sites are mostly dead
views. So the trigger works everywhere the package installs: live views
and controller-rendered pages alike. The keyboard shortcut itself lives
on the dialog; the `kbd` chip here is the visible hint.

## Attributes

* `dialog_id` (`:string`) (required) - the command_dialog this trigger opens.
* `variant` (`:string`) - pill is the labelled search affordance for wide headers; icon is the compact trigger. Defaults to `"pill"`. Must be one of `"pill"`, or `"icon"`.
* `label` (`:string`) - pill text, and the icon variant's aria-label. Defaults to `"Search…"`.
* `kbd` (`:string`) - the shortcut hint rendered on the pill. Set nil to hide it. Defaults to `"⌘K"`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `open_command`

Returns a `JS` command that opens the command dialog with the given id.
Compose it onto any trigger: `phx-click={open_command("cmdk")}`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*