Skip to main content
xriptxr

List

Info:Content
127

A navigable, optionally-selectable collection of items — the reference skin over the shared collection substrate.

listbox options select multiselect collection roving menu

Live demo

live · @xtyle/astro

List

Single-select

A listbox: arrow to move the cursor, Enter or click to choose. Lead icons and trailing text ride the item anatomy.

Plan
  • Starter$0
  • Pro$12
  • Team$40

Multi-select and range

Plain click replaces; Ctrl/Cmd-click toggles; with selection="range", Shift-click extends a span. Under a high-contrast theme the selected rows gain a check.

Toppings
  • Cheese
  • Basil
  • Chili
  • Olives
  • Onion
Days
  • Mon
  • Tue
  • Wed
  • Thu
  • Fri

Sections, toggles and tones

An item with heading: true opens a labelled section; the cursor passes over it. An item with checked is a toggle row that leads with a check and announces its state, in whatever words checkedLabel and uncheckedLabel give it. A tone on a heading paints its whole section, and on an item paints that row.

Settings
  • Play
    • Text speedFast
    • Music, on
  • Display
    • Interface scale100%
    • Reduce motion, off
  • Danger zone
    • Erase all data
    • Reset settings

Sections in columns

Each section's rows sit in a group-items part. Make list a grid and both group and group-items subgrids, and every section's rows share the same columns while one cursor walks them all.

Settings
  • Play
    • Text speedFast
    • Music, checked
  • Display
    • Interface scale100%
    • Reduce motion, not checked
  • Danger zone
    • Erase all data
    • Reset settings

Descriptions, badges and trailing fields

A description adds a second line, a badge a toned chip, and a list of trail fields becomes columns, each its own trail-N part to size.

Saves
  • Slot 1Harbor district, day 12latest3h 40mLv 14
  • Slot 2Northern pass, day 92h 05mLv 9
  • Slot 3Old mine, day 31lockedbackup11h 12mLv 27

Variants, accelerators, separators and trail tones

A variant fills or rings a row in its tone, an accelerator underlines the key that takes it, a separator breaks a list without a heading, and trailTone inks only the trailing fields, like a price the player cannot afford.

Paused
  • Resume
  • Options
  • Retire
  • Quit
Shop
  • Rope12g
  • Lantern40g
  • Old map250g

Navigational

A roving list of destinations: no persistent selection, each item activates.

Jump to
  • Overview
  • Install
  • Search the docs⌘K

Actionable

Per-item actions appear on hover or focus; each emits a list-action event.

Files
  • README.md
  • index.ts
  • styles.css

Sizes

Small
  • One
  • Two
  • Three
Large
  • One
  • Two
  • Three

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.

A badge is the list's own chip rather than a nested <xtyle-badge>, so a row stays one fill a mod can reshape, and its tones read the same --{tone}-vivid ink as a toned row.
Built on the collection substrate: the roving navigation, selection model, and item anatomy are the same core the menu, tree, tabs, segmented, combobox, command-palette, and pagination components share.

Props

9 props, straight from the manifest.

PropTypeDefaultBindingsDescription
items string | (string | ListItem)[] —
html svelte astro
The items, as a comma-string shorthand (label:value pairs or bare labels) or a structured array carrying lead/trail/actions. 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.
interaction "static" | "navigational" | "selectable" | "actionable"
static navigational selectable actionable
navigational
html svelte astro
The interaction posture: presentational, keyboard-navigable, selectable, or navigable with per-item actions.
selection "none" | "single" | "multi" | "range"
none single multi range
none
html svelte astro
The selection model (only meaningful under interaction="selectable"). Ctrl/Cmd-click toggles, Shift-click extends a range.
orientation "vertical" | "horizontal"
vertical horizontal
vertical
html svelte astro
The list flow and the roving arrow-key axis.
size "sm" | "md" | "lg"
sm md lg
md
html svelte astro
The item type scale.
label string —
html svelte astro
A visible group label; use labelledby or aria-label instead where a visible label would be noise.
labelledby string —
html svelte astro
The id of an element elsewhere on the page that names the list, for a heading the list already sits under.
checkedLabel html: checked-label string checked
html svelte astro
The state word announced after a checked toggle row's label, for a list in another language.
uncheckedLabel html: unchecked-label string not checked
html svelte astro
The state word announced after an unchecked toggle row's label.

Events

What the component emits, and what rides along on event.detail. The name in the first column is the one addEventListener takes.

EventDetailBindingsDescription
select { value, index }
html svelte astro
An item was activated.
change { value, values }
html svelte astro
The selection changed.
list-action svelte: onlistaction { value, action }
html svelte astro
An item's trailing action button was activated.

Appearance

Variants

solid

.xtyle-list__item--solid

A row filled with its tone (accent when it names none), set per item through variant.

outline

.xtyle-list__item--outline

A row ringed and inked in its tone.

subtle

.xtyle-list__item--subtle

A row on its tone's soft background.

Sizes

sm

.xtyle-list--sm

Compact rows.

md

default
.xtyle-list--md

Default rows.

lg

.xtyle-list--lg

Roomy rows.

States

active

.xtyle-list__item:focus-visible

The item under the roving keyboard cursor (focus), distinct from selection.

selected

.xtyle-list__item[aria-selected="true"]

A chosen item, marked with an accent fill and, under --selection-cue: marker, a redundant check.

disabled

.xtyle-list__item[aria-disabled="true"]

A non-interactive item, skipped by roving.

checked

.xtyle-list__item[data-checked="true"]

A toggle row that is on: its check mark fills and takes the accent ink.

toned

.xtyle-list__item[class*="xtyle-list__item--"]

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

Success:::part(root) .xtyle-list-shell

The host container.

list

Success:::part(list) .xtyle-list

The list/listbox element holding the items.

--space-1 --font-sans --text-body --fg-1

item

Success:::part(item) .xtyle-list__item

One row: lead, content, trail, and (when actionable) actions.

--space-2 --space-3 --radius-sm --state-hover --accent-bg --fg-0 --fg-disabled

lead

Success:::part(lead) .xtyle-list__lead

A leading icon.

--fg-2

label

Success:::part(label) .xtyle-list__label

The item's primary text.

trail

Success:::part(trail) .xtyle-list__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.

--fg-2 --text-sm

content

Success:::part(content) .xtyle-list__content

The label and its description stacked, present only on an item carrying a description.

description

Success:::part(description) .xtyle-list__description

A second line under the label, the row's aria-describedby.

--fg-2 --text-sm

badge

Success:::part(badge) .xtyle-list__badge

A chip beside the label, optionally toned. Announced with the row.

--space-1 --border-thin --radius-sm --fg-2 --text-xs

actions

Success:::part(actions) .xtyle-list__actions

The per-item action cluster (actionable posture); each button emits a list-action event.

group

Success:::part(group) .xtyle-list__group

A section: a heading item and the items after it, up to the next heading, labelled by that heading.

--space-1 --space-2

group-items

Success:::part(group-items) .xtyle-list__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

Success:::part(heading) .xtyle-list__heading

A section's heading text. Never focused, selected, or activated.

--text-sm --weight-semibold --fg-2

accelerator

Success:::part(accelerator) .xtyle-list__accelerator

The first letter of the label matching the item's accelerator, underlined.

separator

Success:::part(separator) .xtyle-list__separator

A break between rows with no text of its own, from an item carrying separator.

--border-thin --line --space-1

check

Success:::part(check) .xtyle-list__check

A toggle row's check mark, drawn for any item carrying checked.

--fg-2 --accent

state

Success:::part(state) .xtyle-list__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.

Success:fully covered 127/127 consumed tokens produced default register: 311 tokens

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-vivid

Accessibility

A selectable list is a role=listbox of role=option items with aria-selected; multi and range add aria-multiselectable. A non-selectable list is role=list of role=listitem.
Roving tabindex: exactly one item is in the tab order; arrow keys move the cursor, Home/End jump to the ends. Focus (the roving cursor) is kept distinct from selection.
Selection is never color-only: under --selection-cue: marker the selected item gains a redundant check.
Provide a label, labelledby, or aria-label so the list is announced.
A heading opens a section labelled by it (role=group inside a listbox, a nested list otherwise), so a screen reader announces the section a row belongs to. The heading itself is never in the tab order or the selection.
A toggle row (an item carrying checked) is announced with its state: aria-checked on an option, a visually hidden ", checked" / ", not checked" after the label on a listitem, which cannot carry aria-checked; checkedLabel and uncheckedLabel translate those words. The check mark itself is aria-hidden.
An accelerator is carried as aria-keyshortcuts on its row; the underline is decoration. A separator is role=none and aria-hidden, since a list cannot own a separator role, so a break that means something to a listener is a heading instead.
A description is the row's aria-describedby, so it is read after the label rather than as part of the name. A badge is text in the row and is read with it; put status a row must announce there, not in a lead icon.

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>

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>

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>

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>

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>

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>