Components ds-listbox
Listbox
Single-select list with virtual focus: the listbox keeps DOM focus and points at its active option with aria-activedescendant, so a combobox can drive the same list from its own input.
Live playground
Produce
Apple
Apricot
Banana
Blackberry
Blueberry
Cherry
Asparagus
Broccoli
Carrot
Celery
Spinach
Tab into the list, then use the arrow keys, Home and End, or type the start of a name. Enter, Space or a click selects.
- aria-activedescendant
- none
- selected
- banana
- ds-select
- none yet
These buttons call moveActiveOption() and selectOption() without focusing the list, as a combobox input will.
Interactive props
Usage example
<span id="produce-label">Produce</span>
<ds-listbox
aria-labelledby="produce-label"
@ds-select=${(e) => console.log(e.detail.value)}
>
<ds-option-group label="Fruit">
<ds-option value="apple">Apple</ds-option>
<ds-option value="cherry" disabled>Cherry</ds-option>
</ds-option-group>
<ds-option-group label="Vegetables">
<ds-option value="carrot" selected>Carrot</ds-option>
</ds-option-group>
</ds-listbox>
// A control that keeps DOM focus, such as a combobox input:
const option = listbox.moveActiveOption('next');
input.setAttribute('aria-activedescendant', option?.id ?? '');
Keyboard
| Key | Result |
|---|---|
| Tab | Enters the list once. The selected option becomes active, or the first option when none is selected. |
| Arrow Down / Up | Moves the active option, stopping at the ends. |
| Home / End | Moves to the first or last option. |
| Characters | Moves to the next option starting with the typed text. A pause of half a second starts a new search. |
| Enter / Space | Selects the active option. |
API Reference
| Member | Kind | Description |
|---|---|---|
| activeOption | getter | The option keyboard actions apply to, or null. |
| selectedOption | getter | The selected option, or null. |
| options | getter | Every option, in document order. |
| moveActiveOption(move) | method | Moves to the 'next', 'previous', 'first' or 'last' option and returns it. |
| setActiveOption(option) | method | Makes an option active, or clears it with null. |
| selectOption(option) | method | Selects an option as a click does, firing ds-select. |
| ds-select | event | An option was chosen. Detail: {option, value}. |
| ds-active-change | event | The active option changed. Detail: {option}. |
| ds-option | element | value, selected and disabled properties; label is its text. |
| ds-option-group | element | label property: the visible heading and accessible name. |