Skip to main content
xtylext xtyle
xriptxr

List
Info:Content
19

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

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.

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

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

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

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.

Anatomy

The named parts that make up the component. A ::part() handle is reachable from your own stylesheet; the class beside it is the component's internal selector, which a shadow boundary keeps to itself.

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, count, or badge.
--fg-2 --text-sm

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

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

Tokens & coverage

What the component consumes, checked live against what the algorithm produces.

Success:fully covered 19/19 consumed tokens produced default register: 310 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-bg --border-normal --fg-0 --fg-1 --fg-2 --fg-disabled --font-sans --radius-sm --selection-cue --space-1 --space-2 --space-3 --state-hover --text-body --text-lg --text-sm --weight-medium --weight-semibold

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.

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>