'/%3e%3cg%20transform='translate(170%20205)%20scale(0.3606)'%20fill='%23111011'%3e%3cpath%20d='M497%20640H359L248%20320%20122%20640H0L256%200z'/%3e%3cpath%20d='M292.43%20640H200.8L248%20522z'/%3e%3cpath%20d='M335%200h138l111%20320L710%200h122L576%20640z'/%3e%3c/g%3e%3c/svg%3e){kind=small}
Forms
ListBox
A list of options people pick from, shown in the page instead of a popup: single or multiple selection, sections, descriptions and icons, a check at either side, type to jump, scrolling inside a height.
import { ListBox, SelectItem, SelectSection } from '@alea/ui';
Examples
ListBox
Options in the page: single selection with descriptions and icons. Arrows move, typing jumps.
Multiple, sections and plain
selectionMode="multiple" with the check at the start, sections with headings, and the plain look inside your own container with a scrolling height.
Configurations
Every value of every property, side by side. Numbers match the legend below.
- Check Position
checkPosition - Variant
variant - Orientation
orientation
States
Each interaction state, forced so you can compare them, in both themes.
Dark
Light
Anatomy
The parts of the component and the class that styles each one.
Tokens
The design tokens this component reads, with their value in the current theme. Override any of them to restyle it.
Color
--alea-accent-subtle…--alea-border…--alea-focus…--alea-surface…--alea-text-muted…
Radius
--alea-radius-md…
Type
--alea-font-size-sm…
Props
ListBox props
A list of options people pick from, on its own (not in a popup): settings, filters, side lists. Single or multiple selection, sections, descriptions and icons, type to jump.
| Prop | Type | Default | Description |
|---|---|---|---|
checkPosition | "start" | "end" | 'end' | Where the selected check shows: end (default) or start. |
emptyText | ReactNode | - | What shows when the list is empty. |
items | Iterable<T> | - | The options as data, or SelectItem and SelectSection children. |
maxHeight | string | number | - | Scrolls inside this height. |
variant | "plain" | "card" | 'card' | Draws the list as a card with a border (default), or plain inside your own container. |
SelectItem props
An option in a Select (or any listbox).
| Prop | Type | Default | Description |
|---|---|---|---|
description | ReactNode | - | A second line under the option. |
icon | ReactNode | - | An icon before the option. |
SelectSection props
A titled group of options.
| Prop | Type | Default | Description |
|---|---|---|---|
titlerequired | ReactNode | - | The section heading. |
Specs
Generated from the source: the variants in the types, the states and tokens in the CSS, and the motion patterns that apply. The grids render the real component in both themes; the numbers are measured from the page.
ListBox
- Variants
checkPositionstartendvariantplaincard- States
- Keyboard focusSelected
- Dark and light
- Every color comes from theme tokens, so it follows data-theme (and presets like Graphite) on the page or any wrapper. Contrast is checked in both themes.
- Styling hooks
.alea-listbox-empty.alea-listbox-standalone- Data attributes
data-variant=card
SelectItem
- Dark and light
- Every color comes from theme tokens, so it follows data-theme (and presets like Graphite) on the page or any wrapper. Contrast is checked in both themes.
- Styling hooks
.alea-option-icon.alea-option-text.alea-option-desc.alea-option-check- Data attributes
data-check=startdata-on
SelectSection
- Dark and light
- Every color comes from theme tokens, so it follows data-theme (and presets like Graphite) on the page or any wrapper. Contrast is checked in both themes.
- Styling hooks
.alea-option-section.alea-option-header
Accessibility
- A listbox: arrows move, Space or Enter selects, typing jumps to the option that starts with those letters.
- Selected options are announced as selected; disabled ones are skipped.
- Give it a visible label with aria-labelledby, or an aria-label.
Keyboard
| Key | Does |
|---|---|
| Arrow Up / Down | Move |
| Space or Enter | Select |
| Shift + Arrow | Extend the selection (multiple) |
| ⌘A / Ctrl+A | Select all (multiple) |
| Home / End | First or last option |
| Type letters | Jump to a match |
Do and don't
Do
- Use it when the options should stay visible: settings, a side filter, a short list.
Don't
- Don't use it for navigation: use links.
- Don't put long lists in it without maxHeight or a search.