List
A navigable, optionally-selectable collection of items — the reference skin over the shared collection substrate.
Live demo
The plainest collection: a list of items you move a keyboard cursor across and optionally choose among. It is the reference skin over xtyle's shared collection core (roving navigation + the none/single/multi/range selection model + the item anatomy), the same core the specialized list-like components build on.
Reach for it when you want a general list and none of the specialized identities (menu, tree, tabs, combobox).
When to use
How this component composes with the rest of the set.
Props
9 props, straight from the manifest.
| Prop | Type | Default | Bindings | Description |
|---|---|---|---|---|
description adds a second line, badge a chip beside the label, and trail may be a list of fields; trailTone inks the trail alone. variant (solid, outline, subtle) fills or rings a row in its tone, accelerator underlines the key that takes it, and separator: true is a break with no text. An item with checked is a toggle row that leads with a check mark and announces its state. An item with heading: true opens a labelled section; tone paints a row, or a heading's whole section, in that tone's on-surface ink. Also accepts a JSON string on the attribute. | ||||
id of an element elsewhere on the page that names the list, for a heading the list already sits under. | ||||
Events
What the component emits, and what rides along on event.detail. The name in the
first column is the one addEventListener takes.
| Event | Detail | Bindings | Description |
|---|---|---|---|
Appearance
Variants
solid
A row filled with its tone (accent when it names none), set per item through variant.
outline
A row ringed and inked in its tone.
subtle
A row on its tone's soft background.
Sizes
sm
Compact rows.
md
Default rows.
lg
Roomy rows.
States
active
The item under the roving keyboard cursor (focus), distinct from selection.
selected
A chosen item, marked with an accent fill and, under --selection-cue: marker, a redundant check.
disabled
A non-interactive item, skipped by roving.
checked
A toggle row that is on: its check mark fills and takes the accent ink.
toned
A row, or every row in a section, painted in a tone's on-surface ink. A disabled row keeps its disabled ink.
Anatomy
The named parts that make up the component. Created from script it renders a shadow root, where a ::part() handle is reachable from your own stylesheet and the class beside it is internal. Upgraded over server-rendered markup it renders light DOM, where the class is the handle.
root
The host container.
list
The list/listbox element holding the items.
item
One row: lead, content, trail, and (when actionable) actions.
lead
A leading icon.
label
The item's primary text.
trail
Trailing text: a shortcut or count. With several fields, the first three are also trail-1 to trail-3, so a consumer can size each column to line up across rows.
content
The label and its description stacked, present only on an item carrying a description.
description
A second line under the label, the row's aria-describedby.
badge
A chip beside the label, optionally toned. Announced with the row.
actions
The per-item action cluster (actionable posture); each button emits a list-action event.
group
A section: a heading item and the items after it, up to the next heading, labelled by that heading.
group-items
A section's rows, after its heading. Give it display: grid; grid-template-columns: subgrid alongside group to keep a sectioned list's columns aligned across sections.
heading
A section's heading text. Never focused, selected, or activated.
accelerator
The first letter of the label matching the item's accelerator, underlined.
separator
A break between rows with no text of its own, from an item carrying separator.
check
A toggle row's check mark, drawn for any item carrying checked.
state
A toggle row's state word for assistive technology, visually hidden; a listbox announces through aria-checked instead.
Tokens & coverage
What the component consumes, checked live against what the algorithm produces.
Live coverage check against the xtyle-default register
(derive(xtyleDefault, { anchors }) →
coverComponent(manifest, register)). Every token this component
consumes must be a key the algorithm produces.
--accent--accent--accent-2--accent-2-bg--accent-2-fg--accent-2-text--accent-2-vivid--accent-3--accent-3-bg--accent-3-fg--accent-3-text--accent-3-vivid--accent-4--accent-4-bg--accent-4-fg--accent-4-text--accent-4-vivid--accent-bg--accent-bg--accent-fg--accent-text--accent-vivid--black--black-bg--black-fg--black-text--black-vivid--blue--blue-bg--blue-fg--blue-text--blue-vivid--border-normal--border-thin--brown--brown-bg--brown-fg--brown-text--brown-vivid--cyan--cyan-bg--cyan-fg--cyan-text--cyan-vivid--danger--danger-bg--danger-fg--danger-text--danger-vivid--fg-0--fg-1--fg-2--fg-disabled--font-sans--gray--gray-bg--gray-fg--gray-text--gray-vivid--green--green-bg--green-fg--green-text--green-vivid--info--info-bg--info-fg--info-text--info-vivid--line--neutral--neutral-bg--neutral-fg--neutral-text--neutral-vivid--orange--orange-bg--orange-fg--orange-text--orange-vivid--pink--pink-bg--pink-fg--pink-text--pink-vivid--purple--purple-bg--purple-fg--purple-text--purple-vivid--radius-sm--red--red-bg--red-fg--red-text--red-vivid--selection-cue--space-1--space-2--space-3--state-hover--success--success-bg--success-fg--success-text--success-vivid--text-body--text-lg--text-sm--text-xs--warn--warn-bg--warn-fg--warn-text--warn-vivid--weight-medium--weight-semibold--white--white-bg--white-fg--white-text--white-vivid--yellow--yellow-bg--yellow-fg--yellow-text--yellow-vividAccessibility
Code
Single-select
A listbox where one item is chosen at a time.
<xtyle-list label="Plan" interaction="selectable" selection="single" items="Starter,Pro,Team"></xtyle-list><List label="Plan" interaction="selectable" selection="single" items="Starter,Pro,Team" /><List label="Plan" interaction="selectable" selection="single" items="Starter,Pro,Team" />Multi-select
Ctrl/Cmd-click toggles items; Shift-click (with selection="range") extends a span.
<xtyle-list label="Toppings" interaction="selectable" selection="multi" items="Cheese,Basil,Chili,Olives"></xtyle-list><List label="Toppings" interaction="selectable" selection="multi" items="Cheese,Basil,Chili,Olives" /><List label="Toppings" interaction="selectable" selection="multi" items="Cheese,Basil,Chili,Olives" />Sections, toggles and tones
Headings split one list into labelled sections that the cursor passes over; a checked row is a toggle, announced in the words checkedLabel and uncheckedLabel give it; a toned heading paints its whole section.
<xtyle-list label="Settings" checked-label="on" unchecked-label="off" items='[
{"value":"play","label":"Play","heading":true},
{"value":"speed","label":"Text speed","trail":"Fast"},
{"value":"music","label":"Music","checked":true},
{"value":"danger","label":"Danger zone","heading":true,"tone":"danger"},
{"value":"wipe","label":"Erase all data"}
]'></xtyle-list><List label="Settings" checkedLabel="on" uncheckedLabel="off" items={[
{"value":"play","label":"Play","heading":true},
{"value":"speed","label":"Text speed","trail":"Fast"},
{"value":"music","label":"Music","checked":true},
{"value":"danger","label":"Danger zone","heading":true,"tone":"danger"},
{"value":"wipe","label":"Erase all data"}
]} /><List label="Settings" checkedLabel="on" uncheckedLabel="off" items={[
{"value":"play","label":"Play","heading":true},
{"value":"speed","label":"Text speed","trail":"Fast"},
{"value":"music","label":"Music","checked":true},
{"value":"danger","label":"Danger zone","heading":true,"tone":"danger"},
{"value":"wipe","label":"Erase all data"}
]} />Variants, accelerators, separators and trail tones
A pause menu with underlined keys, a break before its weighty choices, rows filled or ringed in a tone, and a price inked on its own.
<xtyle-list label="Paused" items='[
{"value":"resume","label":"Resume","accelerator":"r"},
{"value":"break","label":"","separator":true},
{"value":"retire","label":"Retire","accelerator":"t","variant":"subtle"},
{"value":"quit","label":"Quit","accelerator":"q","variant":"outline","tone":"danger"},
{"value":"map","label":"Old map","trail":"250g","trailTone":"danger"}
]'></xtyle-list><List label="Paused" items={[
{"value":"resume","label":"Resume","accelerator":"r"},
{"value":"break","label":"","separator":true},
{"value":"retire","label":"Retire","accelerator":"t","variant":"subtle"},
{"value":"quit","label":"Quit","accelerator":"q","variant":"outline","tone":"danger"},
{"value":"map","label":"Old map","trail":"250g","trailTone":"danger"}
]} /><List label="Paused" items={[
{"value":"resume","label":"Resume","accelerator":"r"},
{"value":"break","label":"","separator":true},
{"value":"retire","label":"Retire","accelerator":"t","variant":"subtle"},
{"value":"quit","label":"Quit","accelerator":"q","variant":"outline","tone":"danger"},
{"value":"map","label":"Old map","trail":"250g","trailTone":"danger"}
]} />Descriptions, badges and trailing fields
A save-slot list: a second line under each label, a toned chip, and two trailing columns sized through trail-1 and trail-2 so they line up across rows.
<xtyle-list label="Saves" interaction="selectable" selection="single" items='[
{"value":"slot-1","label":"Slot 1","description":"Harbor district, day 12","trail":["3h 40m","Lv 14"],"badge":{"text":"latest","tone":"success"}},
{"value":"slot-2","label":"Slot 2","description":"Northern pass, day 9","trail":["2h 05m","Lv 9"],"badge":[{"text":"locked","tone":"warn"}]}
]'></xtyle-list>
<style>xtyle-list::part(trail-1) { min-width: 4.5rem; } xtyle-list::part(trail-2) { min-width: 3rem; }</style><List label="Saves" interaction="selectable" selection="single" items={[
{"value":"slot-1","label":"Slot 1","description":"Harbor district, day 12","trail":["3h 40m","Lv 14"],"badge":{"text":"latest","tone":"success"}},
{"value":"slot-2","label":"Slot 2","description":"Northern pass, day 9","trail":["2h 05m","Lv 9"],"badge":[{"text":"locked","tone":"warn"}]}
]} /><List label="Saves" interaction="selectable" selection="single" items={[
{"value":"slot-1","label":"Slot 1","description":"Harbor district, day 12","trail":["3h 40m","Lv 14"],"badge":{"text":"latest","tone":"success"}},
{"value":"slot-2","label":"Slot 2","description":"Northern pass, day 9","trail":["2h 05m","Lv 9"],"badge":[{"text":"locked","tone":"warn"}]}
]} />Sections in columns
A sectioned list laid out two to a row. list becomes a grid, and group and group-items become subgrids, so every section's rows share one set of columns and one cursor.
<xtyle-list class="columns" label="Settings" items='[
{"value":"play","label":"Play","heading":true},
{"value":"speed","label":"Text speed","trail":"Fast"},
{"value":"music","label":"Music","checked":true},
{"value":"danger","label":"Danger zone","heading":true,"tone":"danger"},
{"value":"wipe","label":"Erase all data"}
]'></xtyle-list>
<style>
.columns::part(list) { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }
.columns::part(group), .columns::part(group-items) { grid-column: 1 / -1; display: grid; grid-template-columns: subgrid; }
.columns::part(heading) { grid-column: 1 / -1; }
</style><List class="columns" label="Settings" items={[
{"value":"play","label":"Play","heading":true},
{"value":"speed","label":"Text speed","trail":"Fast"},
{"value":"music","label":"Music","checked":true},
{"value":"danger","label":"Danger zone","heading":true,"tone":"danger"},
{"value":"wipe","label":"Erase all data"}
]} /><List class="columns" label="Settings" items={[
{"value":"play","label":"Play","heading":true},
{"value":"speed","label":"Text speed","trail":"Fast"},
{"value":"music","label":"Music","checked":true},
{"value":"danger","label":"Danger zone","heading":true,"tone":"danger"},
{"value":"wipe","label":"Erase all data"}
]} />