List

Web components for lists with selectable, checkbox, radio and switch items, plus ARIA listbox and combobox controllers.

A list of items, such as mo-list-items and the ones with a checkbox, switch or radio button.

Installation

npm install @3mo/list

import '@3mo/list'

Usage

<mo-list>
    <mo-list-item icon='inbox'>Inbox</mo-list-item>
    <mo-list-item icon='drafts'>Drafts</mo-list-item>
    <mo-list-item icon='send'>Sent</mo-list-item>
    <mo-list-item icon='delete'>Trash</mo-list-item>
</mo-list>

Examples

• Content — An item holds any content after its icon, such as a shortcut at its end, and an element with role='separator' divides the groups.
• Disabled — A disabled item fades and ignores presses; an element inside it can still take them with pointer-events: auto.
• Subgrid Layout — A list laid out as a grid whose items take its columns through subgrid lines up the icons, labels and shortcuts of all items.
• Checkbox Items — mo-checkbox-list-item makes the whole item the label of its checkbox.
• Switch Items — mo-switch-list-item does the same for a switch.
• Radio Items — mo-radio-list-item does the same for a radio button.
• Selection Control Alignment — selectionControlAlignment='start' places the control before the content instead of at its end.
• Selectable Items — A toggleable selectable item is selected and deselected by a press, and shows its state by its background.
• Collapsible Items — mo-collapsible-list-item opens its details below the item it holds, to any depth.
• Selectable List — mo-selectable-list keeps one selection over all its selectable items, whatever their control, as their indices in value; arrow keys move between them.
• Selectable Collapsible Items — Selectable items inside collapsible ones join the list's selection too; here :has() outlines the group that holds it.

Combobox

• Default — ↓ or ↑ opens the list onto the chosen country and Esc closes it; each new filter makes its first match active, so Enter takes it.
• Search In Popup — A button opens a popup with its own search box, which is the combobox.

Listbox

• Default — Tab in, then the arrows, Home, End and typing a name move; Space or Enter selects.
• Selection Follows Focus — selectionFollowsFocus selects whichever option the arrows reach, as a single-select listbox of few options may.
• Horizontal — orientation: 'horizontal' moves with ← and →, which follow the writing direction.
• Multiple Selection — Space or a click toggles one option, Shift+arrow and Shift+Space extend a range, Ctrl+Shift+Home or End select to either end, and Ctrl+A selects all or none.
• Filter As You Type — With combobox, focus stays in the input and the active option is announced on it by element reference; Home, End, ← and → stay the input's.
• Grouped — Options in labelled groups: the arrows run straight on from one group into the next, while a screen reader counts within each.

Accessibility

mo-list

A list of listitems: every item is a tab stop, and Enter and Space click it. For a choice among the items use mo-selectable-list, a listbox. ArrowRight opens a mo-collapsible-list-item and ArrowLeft closes it. It does not announce whether it is open yet, and the two keys do not swap in a right-to-left language.

ListboxController

The list is a listbox, with aria-multiselectable while multiple and aria-orientation='horizontal' when horizontal. Each option is an option with aria-selected, and aria-disabled while disabled. Focus roves: Tab lands on the first selected option, else on the first one. The arrows move without selecting, unless selectionFollowsFocus selects as they move in single selection.

Name the list with aria-label or aria-labelledby.

ComboboxController

The input is a combobox with aria-expanded and aria-controls pointing at the listbox, whose options follow the listbox pattern. Focus stays in the input: the active option is named by aria-activedescendant, set as an element reference so it reaches options in another shadow root, and gets data-keyboard-focus so it can show a focus ring.

Name the input and the listbox, for example after a visible label.

Another popup takes the listbox's place through popup: a tree's controller given the input as its combobox, for options nested under others. Its keys and roles are the tree's own.

API

mo-list

Events

Slots

mo-checkbox-list-item

A list item with a checkbox, which a press anywhere on the item toggles.

Properties

Events

Slots

CSS parts

mo-collapsible-list-item

A list item that opens into the nested items below it.

Properties

Slots

CSS parts

mo-list-item

An item of a list, with an optional icon before its content.

Properties

Slots

CSS parts

mo-list-item-ripple

Properties

mo-navigation-list-item

Properties

Slots

CSS parts

mo-radio-list-item

A list item with a radio button, which a press anywhere on the item selects.

Properties

Events

Slots

CSS parts

mo-selectable-list

A list that keeps one selection over its selectable items, whichever their control, by their indices.

Properties

Events

Slots

mo-selectable-list-item

A list item that a press selects, shown by its background.

Properties

Events

Slots

CSS parts

mo-switch-list-item

A list item with a switch, which a press anywhere on the item toggles.

Properties

Events

Slots

CSS parts

Links

• Documentation
• Changelog
• Source

License

MIT © 3MO GmbH