ki-list

A non-interactive vertical list container for read-only collections of similar entries, composed with ki-list-item children.

Ada Lovelace Analyst Active Grace Hopper Rear admiral Away

<ki-list>
<ki-list-item>
  <ki-avatar slot="start" initials="AL" label="Ada Lovelace"></ki-avatar>
  Ada Lovelace
  <span slot="secondary">Analyst</span>
  <ki-badge slot="end" tone="success">Active</ki-badge>
</ki-list-item>
<ki-list-item>
  <ki-avatar slot="start" initials="GH" label="Grace Hopper"></ki-avatar>
  Grace Hopper
  <span slot="secondary">Rear admiral</span>
  <ki-badge slot="end" tone="neutral">Away</ki-badge>
</ki-list-item>
</ki-list>

API reference

When to use: settings, contacts, results or activity feeds where each item composes leading media, primary text, optional secondary text and trailing meta or a slotted control.

When not to use: menus, selectable option lists, tabular data, navigation, whole-item clickable rows or lone items outside a list.

Slots

Slot	Description
(default)	ki-list-item children. Other children are unsupported.

CSS parts

Part	Description
list	List surface that owns background, padding, item gap and between-item divider styling.

CSS custom properties

The public styling contract of ki-list: reassign these tokens at :root or on a subtree — never override internals.

Token	Description
--ki-list-bg	color used by the list component for background.
--ki-list-gap	dimension used by the list component for gap (MarsUI compositions stack rows contiguously; --ki-list-gap stays as the theme hook).
--ki-list-item-divider-color	color used by the list component for item divider color.
--ki-list-item-divider-width	dimension used by the list component for item divider width (no divider renders in any master variant; the color hook ki.list.item.divider-color stays so consumers can opt hairlines back in).
--ki-list-padding	dimension used by the list component for padding.
--ki-motion-distance-xs	Motion travel distance xs (2px): hover-lift offsets.
--ki-motion-duration-fast	Fast interaction transition duration.
--ki-motion-duration-medium-1	M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base).
--ki-motion-easing-out	Decelerating interaction transition easing curve.
--ki-typography-family-body	semantic font family for typography family body.

Accessibility

The list is read-only: menus, selectable option lists, tabular data and navigation are different patterns with different semantics — use a menu, ki-select, a table or links respectively. A slotted control inside an item (in end, say) stays an ordinary, individually focusable control; whole-item clickable rows are unsupported.

Workshop

Open ki-list in Storybook