Command

Usage

The command-palette pattern. Bits owns the filtering, the scoring and arrow-key navigation, and it keeps focus in the Input while the highlight moves — so the user types and navigates without ever leaving the field. To open it in a modal, wrap the whole thing in a Dialog.

Try typing trash — it matches Delete, which does not contain the word.

Viewport is required

Command.Viewport goes inside List and wraps the content. It is not optional.

Bits takes the Input's aria-controls from the Viewport's id, and uses the Viewport as the insertion element when sorting filtered items. Omit it and the combobox is invalid ARIA — axe reports aria-required-attr, because a role="combobox" with aria-expanded must say what it controls.

This is not hypothetical: our own a11y suite caught a Command built without one, which is why it is called out here rather than left as a detail in the API table.

Naming the field and the list

There are two names to set, and the prop names do not make that obvious:

• label on Root names the search field. It renders a visually hidden <label> that the Input references.
• aria-label on List names the list. Bits defaults it to "Suggestions...", which says nothing about what the suggestions are — override it.

We deliberately leave Bits' default in place rather than silently substituting our own, so the behaviour matches their documentation. Setting both is on you.

Keywords and filtering

value is what the query matches against. Add keywords for the words a user would actually type but that are not in your label — trash on a Delete item, preferences on Settings. This is the difference between a palette people use and one they abandon because it never finds anything.

A group whose items are all filtered out is hidden along with its heading, so you never get a heading over nothing. Set shouldFilter=false when you filter server-side and render only what you want shown.

Async results

Use Loading while a request is in flight, not Empty. "No results" and "still loading" are different answers, and showing the first one during a fetch tells the user to stop typing when they should wait.

Announcing results

Bits filters the list and announces nothing. Without Command.Status, a screen reader user types and the list shrinks in silence — they never learn whether they have forty matches or none.

<Command.Root label="Command palette">
  <Command.Input bind:value={search} />

  <!-- Once, anywhere inside Root. Pass a label in your language. -->
  <Command.Status label={(n) => (n === 1 ? '1 resultado' : `${n} resultados`)} />

  <Command.List aria-label="Commands">
    <Command.Viewport>…</Command.Viewport>
  </Command.List>
</Command.Root>

It is a visually hidden role="status" region. Hidden because the count is already on screen — the results are right there — so duplicating it visibly would be noise for everyone else.

Pass label. The default is English, and a count is exactly the kind of string that needs your language and plural rules.

delay is not a performance tweak. Without it, typing "button" fires six announcements — "48 results", "12 results", "4 results" — and the user hears a torrent instead of an answer. Each keystroke restarts the wait, so they get one answer once they stop typing. The default is 500ms.

It stays silent until the search is non-empty: the count of an unfiltered list is not news when a palette opens, and it falls silent again if the search is cleared.

Combobox needs the same thing and gets no component, deliberately — Bits does not filter there, you do, so you already know the count. Render your own region with it. There is nothing this library can add that you do not already have.

Props

Command.Root

Command.Input

Command.List

Command.Item

Command.Status

Command.Item

Input, List, Group, GroupHeading, Empty, Separator and Loading take class plus their native attributes. Viewport, GroupItems and LinkItem are re-exported from Bits unchanged.