Skip to content

Listbox

One list of options a person picks from, with groups, filtering, typeahead and selection.

Anatomy

<div class="cap-listbox" data-cap="listbox" data-selection="single" role="listbox" aria-label="Region" tabindex="0">
  <div class="cap-listbox-group" role="group" aria-labelledby="g-eu">
    <div class="cap-listbox-label" id="g-eu" role="presentation">Europe</div>
    <div class="cap-option" id="r-fra" role="option" aria-selected="false" data-value="fra" data-keywords="germany">
      <span class="cap-option-label">Frankfurt</span>
      <span class="cap-option-keys"><span class="cap-sr-only">, shortcut </span><kbd>f</kbd></span>
      <span class="cap-option-indicator" aria-hidden="true"><svg viewBox="0 0 16 16">...</svg></span>
    </div>
  </div>
  <div class="cap-listbox-separator" aria-hidden="true"></div>
</div>
<p class="cap-listbox-empty" role="status"></p>
import { enhance, createListbox, listboxFor, filterCommands, groupBy, step, stepEnabled, nextTypeahead } from "capsomer/behavior/listbox";
enhance(); // every [data-cap="listbox"]
const lb = createListbox(el, { input, selection: "single", wrap: true, rank });
lb.filter("fra");              // shows the matches, announces the count, returns it
lb.step(1); lb.select();       // move the active option, choose it
el.addEventListener("cap:option-select", (e) => e.detail); // { option, value, label, selected, values }
ClassIs
.cap-listboxthe root
.cap-listbox-emptya part
.cap-listbox-groupa part
.cap-listbox-labela part
.cap-listbox-separatora part
.cap-option-hintits own class
.cap-option-indicatorits own class

Data attributes

AttributeValues
data-activepresent or absent
data-cap-readypresent or absent
data-controlledpresent or absent
data-disabledpresent or absent
data-highlightedpresent or absent
data-modedescendant roving
data-selectionmulti single
data-tonecrit
data-uncheckedpresent or absent
data-variantsurface
StateRead from
:emptythe platform
:focus-visiblethe platform
:focus-withinthe platform
:hoverthe platform
[aria-checked="false"]an attribute
[aria-disabled="true"]an attribute
[aria-selected="false"]an attribute
[hidden]an attribute

Keyboard

KeyDoes
Down arrow, Up arrowMoves the active option, skipping disabled ones
Home, EndFirst, last option (with an input: only when homeEnd is set; otherwise the caret moves)
Page Down, Page UpMoves about a screenful
EnterChooses the active option (with selection "none": reports it)
SpaceSame, when no input holds focus and no typeahead is under way
A letterMoves to the next option starting with it; more letters within 0.7 s make a longer prefix (not with an input)
TabLeaves the list; in roving mode enters on the chosen option

API

Listbox

PropTypeRequiredDoes
selectionSelectionName it: aria-label or aria-labelledby.
modeListboxMode
variant"surface"Draws its own border and surface, for a list on its own page.
controlledbooleanSet when something else (Base UI, your own handler) moves the highlight, so the pointer does not also light the row under it.

And every attribute of <element>.

Option

PropTypeRequiredDoes
idstringYesRequired for aria-activedescendant to name it.
valuestring
selectedbooleanChosen. Leave undefined in a list where nothing is chosen (a command menu).
activebooleanThe current option (the one Enter acts on).
disabledboolean
tone"crit"
keywordsreadonly string[]Other words that find it.
iconReactNode
hintReactNodeA note in words, read after the label: "asks a reason".
keysreadonly string[] | ReactNodeShortcut caps ["g", "o"], or any node.

And every attribute of <element>.

OptionGroup

PropTypeRequiredDoes
labelReactNodeYes

And every attribute of <element>.

ListboxSeparator

ListboxEmpty

PropTypeRequiredDoes
childrenReactNode

ListboxStatus

PropTypeRequiredDoes
countnumberYes
filteredbooleanYes

Functions

FunctionSignatureDoes
matchesQuery(c: Searchable, query: string): booleanCase-insensitive substring over the group, the label and the keywords, so the name of a group finds all of it. An empty query matches all.
filterCommands<T extends Searchable>(items: readonly T[], query: string, rank?: Rank<T> | undefined): T[]The items that match, in their own order; or, with a rank, the items it scores, best first. The rank replaces the substring test, so it may match more loosely (a subsequence, say).
groupBy<T>(items: readonly T[], by?: (item: T) => string | undefined): { group: string; items: T[]; }[]Items by group, in the order each group first appears. An item with no group falls under "".
step(index: number, by: number, count: number, wrap?: boolean): numberMoves an index by by. Stops at the ends, or with wrap goes round. From no index (-1) a forward move lands on the first and a backward move on the last.
stepEnabled(disabled: readonly boolean[], index: number, by: number, wrap?: boolean): numberstep over a row where some entries cannot be chosen. A single step lands on the next enabled entry in that direction (wrapping if asked); a longer step (a page) lands on the enabled entry nearest its target. Returns the current index when there is nowhere to go, and -1 when nothing is enabled.
nextTypeahead(state: TypeaheadState, key: string, now: number, labels: readonly (string | null)[], current: number, timeout?: number): { state: TypeaheadState; index: number; }Typeahead over a list of labels (null for an entry that cannot be chosen). Characters typed within timeout ms of each other make one prefix; the first match from the current entry on wins, wrapping. One letter pressed again and again (or a single letter after a pause) cycles through the entries that start with it. index is -1 when nothing matches.
resultsText(count: number): stringThe words a polite live region says after filtering.
emptyText(query: string): string
createListbox(el: HTMLElement, opts?: ListboxOptions): Listbox
listboxFor(el: Element | null): Listbox | undefinedThe controller enhance made for this element, if any.
enhance(root?: ParentNode): () => voidAttaches to every [data-cap="listbox"] under root not yet marked data-cap-ready. Reads data-mode ("input" is found by the combobox whose aria-controls names this list), data-selection ("single", "multi"), data-wrap, and data-filter (typing in the input filters). Returns a function that detaches them all.

CSS variables

VariableDefault
--available-height60dvh
--listbox-maxmin(18rem, var(--available-height, 60dvh))