components command

components/command

Import: import { CommandList, Command } from "@tundralibs/ui/command"

Rendered in every variant on the catalogue (deno task build:demos, then demo/index.html). Guides: Getting started · rAPId integration · Theming.

Functions

CommandList

CommandList(props: CommandListProps): Html

The result list alone — what a route returns for a swap of #<id>-list.

Command

Command(props: CommandProps): Html

Types

CommandItem

Prop	Type	Required	Description
label	string	yes
group	string
href	string
icon	IconName
badge	string		Two-letter badge instead of an icon — used for record results.
meta	string
shortcut	string

CommandProps

Prop	Type	Required	Description
id	string	yes	Required: the result list is the swap target.
query	string
items	CommandItem[]	yes
action	string		URL that returns a fresh CommandList(...) fragment for ?q=<text>; command.js debounces input and swaps it in via window.rapid.swap(). Without it the rendered items are filtered client-side.
open	boolean
inline	boolean		Renders in normal flow instead of over an overlay.
placeholder	string
emptyText	string
label	string		Accessible name of the floating palette dialog.

CommandListProps

type CommandListProps = Pick

Usage

Each example as the rAPId call and the HTML it renders — the markup a plain page writes by hand. Icons are inline SVG in the real output; they are shortened to <svg …>…</svg> here.

A ⌘K palette

⌘K or any [data-command-open="#palette"] opens it; action makes the results server-side.

html`${
  Button({ label: "Search", variant: "outline", size: "sm", attrs: { "data-command-open": "#palette" } })
}${
  Command({
    id: "palette",
    action: "/fragments/commands",
    placeholder: "Jump to…",
    items: [
      { label: "New invoice", group: "Actions", icon: "plus", shortcut: "N" },
      { label: "Contoso Ltd", group: "Clients", badge: "CL", href: "/clients/contoso" },
    ],
  })
}`

<button type="button" class="btn btn--outline btn--sm" data-command-open="#palette">Search</button>
<div class="command" id="palette" data-command hidden>
  <div class="command__sheet" role="dialog" aria-modal="true" aria-label="Command palette">
    <div class="command__search">
      <span class="command__search-icon">
        <svg width="17" height="17" width="2" …>…</svg>
      </span>
      <input class="command__input" type="text" role="combobox" autocomplete="off" aria-label="Run a command" aria-controls="palette-list" aria-expanded="true" value="" placeholder="Jump to…" data-command-action="/fragments/commands" data-command-target="#palette-list">
      <button type="button" class="command__kbd command__esc" data-command-dismiss>esc</button>
    </div>
    <div class="command__list" id="palette-list" role="listbox">
      <div class="command__group" role="presentation">Actions</div>
      <button type="button" class="command__item" id="palette-item-0" role="option">
        <span class="command__item-icon">
          <svg width="16" height="16" width="2" …>…</svg>
        </span>
        <span class="command__item-label">New invoice</span>
        <span class="command__kbd">N</span>
      </button>
      <div class="command__group" role="presentation">Clients</div>
      <a class="command__item" id="palette-item-1" href="/clients/contoso" role="option">
        <span class="command__item-badge">CL</span>
        <span class="command__item-label">Contoso Ltd</span>
      </a>
    </div>
    <div class="command__footer">
      <span>&uarr;&darr; move</span>
      <span>&crarr; run</span>
      <span class="command__count">2 results</span>
    </div>
  </div>
</div>

The fragment the route returns

CommandList({
  id: "palette",
  query: "con",
  items: [{ label: "Contoso Ltd", badge: "CL", href: "/clients/contoso" }],
})

<a class="command__item" id="palette-item-0" href="/clients/contoso" role="option">
  <span class="command__item-badge">CL</span>
  <span class="command__item-label">
    <strong class="command__match">Con</strong>
    toso Ltd
  </span>
</a>

CSS hooks

Classes defined by components/command/command.css — structural, token-driven; override from an unlayered stylesheet (see Theming):

.command, .command--inline, .command__count, .command__empty, .command__esc, .command__footer, .command__group, .command__input, .command__item, .command__item-badge, .command__item-icon, .command__item-label, .command__item-meta, .command__kbd, .command__list, .command__match, .command__search, .command__search-icon, .command__sheet, .command__trigger, .hide-sm

Behaviour

components/command/command.js ships in ui.js (delegated on document, re-initialised after a rAPId swap).

Attributes it reads or writes: data-active, data-command, data-command-action, data-command-dismiss, data-command-open, data-command-target.