Renders an inline command palette modal overlay.

Hidden by default. The PhiaCommand hook shows it on Ctrl+K / Cmd+K and hides it on Escape. The backdrop is a semi-transparent black overlay; clicking it closes the palette.

Use command_dialog/1 for the more common centered, blur-backdrop variant. Use command/1 when you want a simpler overlay or need custom positioning.

Attributes

• id (:string) (required) - Unique ID for the command modal element — the hook mount point.
• class (:string) - Additional CSS classes. Defaults to nil.
• Global attributes are accepted. Extra HTML attributes forwarded to the root <div>.

Slots

• inner_block (required) - command_input/1, command_list/1 and related sub-components.

Renders the standard command palette modal — centered on the viewport with a blurred backdrop.

This is the recommended component for a global application command palette. It differs from command/1 in:

• Vertically centered (not at 20% from top)
• backdrop-blur-sm on the backdrop for a modern frosted-glass appearance
• aria-label for the dialog name

The hook registers Ctrl+K / Cmd+K globally — no separate trigger button is needed (though you can also trigger it programmatically).

Example

<.command_dialog id="app-cmd" title="Application commands">
  <.command_input id="app-cmd-input" on_change="search" />
  <.command_list id="app-cmd-list">
    <.command_group label="Navigation">
      <.command_item on_click="goto" value="/dashboard">Dashboard</.command_item>
      <.command_item on_click="goto" value="/settings">Settings</.command_item>
    </.command_group>
  </.command_list>
</.command_dialog>

Attributes

• id (:string) (required) - Unique ID for the command dialog element — the hook mount point.
• title (:string) - Accessible label used as aria-label for the dialog. Screen readers announce this when the dialog opens. Defaults to "Command Palette".
• class (:string) - Additional CSS classes. Defaults to nil.
• Global attributes are accepted. Extra HTML attributes forwarded to the root <div>.

Slots

• inner_block (required) - command_input/1, command_list/1 and related sub-components.

Renders an empty state message when no command items match the search query.

Show this when the results list is empty. A good empty state is specific about what is missing:

<%= if @cmd_results == [] do %>
  <.command_empty>No results for "{@cmd_query}".</.command_empty>
<% end %>

Avoid generic messages like "No results" — tell users what they searched for so they can refine their query.

Attributes

• class (:string) - Additional CSS classes. Defaults to nil.
• Global attributes are accepted. Extra HTML attributes forwarded to the empty state <div>.

Slots

• inner_block (required) - Empty state message text.

Renders a labeled group of command items.

Use groups to organize results into meaningful categories — "Pages", "Actions", "Recent", "Settings". Groups make large result sets easier to scan quickly.

<.command_group label="Pages">
  <.command_item on_click="navigate" value="/dashboard">Dashboard</.command_item>
  <.command_item on_click="navigate" value="/reports">Reports</.command_item>
</.command_group>
<.command_separator />
<.command_group label="Actions">
  <.command_item on_click="create_record" value="new">New Record</.command_item>
</.command_group>

The group heading is text-xs font-medium text-muted-foreground — visible but not competing with the item content.

Attributes

• label (:string) (required) - Group heading label — describes the category of results in this section.
• class (:string) - Additional CSS classes. Defaults to nil.
• Global attributes are accepted. Extra HTML attributes forwarded to the group <div>.

Slots

• inner_block (required) - command_item/1 sub-components.

Renders the command palette search input.

Uses role="combobox" and aria-autocomplete="list" to declare the ARIA relationship between the input and the results list. The hook manages aria-activedescendant to point at the currently highlighted item.

The phx-change sends a LiveView event on every keystroke — use debouncing in your handler or a phx-debounce attribute for expensive searches:

<.command_input id="cmd-input" on_change="search" phx-debounce="200" />

autocomplete="off" and spellcheck="false" prevent browser autocomplete dropdowns and red underlines from cluttering the search UI.

Attributes

• id (:string) (required) - Input element ID — used by the hook for aria-activedescendant management.

• placeholder (:string) - Placeholder text shown when the input is empty. Defaults to "Type a command or search...".

• on_change (:string) (required) - LiveView event name sent via phx-change on every keystroke. Your handler should update @results (or equivalent assign) with filtered items.

• class (:string) - Additional CSS classes. Defaults to nil.

• Global attributes are accepted. Extra HTML attributes forwarded to the <input>.

Renders a selectable command palette item.

Uses role="option" to pair with the command_list/1's role="listbox". The hook manages aria-selected and the data-selected attribute for the currently highlighted item (driven by ArrowUp/ArrowDown).

When the user presses Enter or clicks the item, phx-click={@on_click} fires with phx-value-value={@value}. Your LiveView handler receives:

def handle_event("navigate", %{"value" => "/dashboard"}, socket) do
  {:noreply, push_navigate(socket, to: "/dashboard")}
end

Add command_shortcut/1 as the last child to show a keyboard hint:

<.command_item on_click="navigate" value="/settings">
  <.icon name="settings" class="mr-2 h-4 w-4" />
  Settings
  <.command_shortcut>⌘,</.command_shortcut>
</.command_item>

Attributes

• on_click (:string) (required) - LiveView event name sent via phx-click when the item is selected.
• value (:string) (required) - Item value sent as phx-value-value — use to pass page paths, IDs, or action keys.
• class (:string) - Additional CSS classes. Defaults to nil.
• Global attributes are accepted. Extra HTML attributes forwarded to the item <div>.

Slots

• inner_block (required) - Item content — icon + label + optional command_shortcut/1.

Renders the command results container.

Uses role="listbox" to form the ARIA combobox pair with the command_input/1 that has role="combobox". Screen readers announce this as the list of available results when the input is focused.

The max-h-72 overflow-y-auto limits the visible height and enables scrolling for long result lists, keeping the palette compact.

Attributes

• id (:string) (required) - Element ID for the results list — the hook links the input's aria-controls here.
• class (:string) - Additional CSS classes. Defaults to nil.
• Global attributes are accepted. Extra HTML attributes forwarded to the list <div>.

Slots

• inner_block (required) - command_empty/1, command_group/1, command_separator/1 sub-components.

Renders a visual divider between command groups.

Use separators to create clear boundaries between unrelated categories in the results list. Typically placed between command_group/1 elements:

<.command_group label="Navigation">...</.command_group>
<.command_separator />
<.command_group label="Actions">...</.command_group>

Attributes

• class (:string) - Additional CSS classes. Defaults to nil.
• Global attributes are accepted. Extra HTML attributes forwarded to the separator <div>.

Renders a right-aligned keyboard shortcut badge inside a command item.

This is presentational only — the shortcut hint does not register any keyboard listener. The shortcut should match an actual global shortcut registered in your application JavaScript.

<.command_item on_click="navigate" value="/preferences">
  <.icon name="sliders" class="mr-2 h-4 w-4" />
  Preferences
  <.command_shortcut>⌘,</.command_shortcut>
</.command_item>

The ml-auto class pushes the shortcut to the far right of the flex container, aligned opposite the item label and icon.

Attributes

• class (:string) - Additional CSS classes. Defaults to nil.
• Global attributes are accepted. Extra HTML attributes forwarded to the <span>.

Slots

• inner_block (required) - Shortcut text — e.g. ⌘K, Ctrl+P, ⌘,. Use platform-specific symbols.