XDS — Design System

XDSList@xds/core · List

Usage

A vertical collection of items with consistent spacing, dividers, and optional markers. Supports headers, icons, avatars, badges, and interactive items with click or link behavior. Use it to display ordered or unordered groups of related content.

Best practices

Guidance	Practices
Do	Provide a header to label the list and give context to screen readers.
Do	Use start and end content slots to add icons, avatars, or badges to each item.
Don't	Place interactive elements inside an interactive list item — it creates nested click targets and confusing focus behavior.
Don't	Use a list for a single item or for laying out unrelated content — lists imply a meaningful collection.
Don't	Mix clickable and non-clickable items in the same list without clear visual distinction.

Anatomy

Element		Description
List title	required	Heading that labels the list.
Description		Supplementary text below the title.
List items	required	Individual entries, which may include icons or images.
Item description		Additional detail for an individual list item.

Import

ts
import {XDSList} from '@xds/core/List'

Props

Prop	Type	Description
children	ReactNode	List items (XDSListItem components).
density	'compact' \| 'balanced' \| 'spacious' (default: 'balanced')	Spacing density for items.
hasDividers	boolean (default: false)	Show dividers between items.
header	ReactNode	Header content, associated with the list via aria-labelledby.
listStyle	'none' \| 'disc' \| 'decimal' \| 'circle' (default: 'none')	List marker style. 'decimal' renders an <ol> element instead of <ul>.
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

Sub-components

List is a compound component with 2 sub-components.

XDSList

List container with density, dividers, and header support.

Prop	Type	Description
children	ReactNode	List items (XDSListItem components).
density	'compact' \| 'balanced' \| 'spacious' (default: 'balanced')	Spacing density for items.
hasDividers	boolean (default: false)	Show dividers between items.
header	ReactNode	Header content, associated with the list via aria-labelledby.
listStyle	'none' \| 'disc' \| 'decimal' \| 'circle' (default: 'none')	List marker style. 'decimal' renders an <ol> element instead of <ul>.
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

XDSListItem

List item with label, description, start/end content slots, and interactive patterns.

Prop	Type	Description
labelrequired	string	Primary text.
description	ReactNode	Secondary content below the label. A plain string gets single-line truncation automatically; a ReactNode lets child components control their own wrapping and line-clamp behavior.
startContent	ReactNode	Content rendered before the label area (e.g. icon, avatar).
endContent	ReactNode	Content rendered after the label area (e.g. badge, chevron).
onClick	(e: MouseEvent) => void	Click handler; enables the invisible button pattern.
href	string	Link URL; enables the invisible anchor pattern.
target	string	Link target attribute, only applicable when href is provided.
isDisabled	boolean (default: false)	Disabled state; sets aria-disabled on the item.
isSelected	boolean (default: false)	Selected state; sets aria-selected on the item.

Examples

Common configurations, variations, and states.

List — BasicSimple list with labels and descriptions for settings-style layouts.

tsx
'use client';
import {XDSList, XDSListItem} from '@xds/core/List';
export default function ListBasicList() {
  return (
    <XDSList>
      <XDSListItem label="Notifications" description="Manage your alerts" />
      <XDSListItem label="Privacy" description="Control your data" />
      <XDSListItem label="Security" description="Password and 2FA" />
    </XDSList>
  );
}

List — Bulleted FeaturesBulleted list of feature highlights using disc markers.

tsx
'use client';
import {XDSList, XDSListItem} from '@xds/core/List';
export default function ListBulletedFeatures() {
  return (
    <XDSList listStyle="disc">
      <XDSListItem label="Accessible by default" />
      <XDSListItem label="Themeable with StyleX" />
      <XDSListItem label="Composable and extensible" />
    </XDSList>
  );
}

List — Message ListChat-style message list with avatars, preview text, and unread badges.

tsx
'use client';
import {XDSList, XDSListItem} from '@xds/core/List';
import {XDSAvatar} from '@xds/core/Avatar';
import {XDSBadge} from '@xds/core/Badge';
export default function ListMessageList() {
  return (
    <XDSList hasDividers>
      <XDSListItem
        label="Alex Johnson"
        description="Hey, are we still on for lunch tomorrow?"
        startContent={<XDSAvatar name="Alex Johnson" size={40} />}
        onClick={() => {}}
        endContent={<XDSBadge label="2" />}
      />
      <XDSListItem
        label="Sam Rivera"
        description="I pushed the latest changes to the repo"
        startContent={<XDSAvatar name="Sam Rivera" size={40} />}
        onClick={() => {}}
      />
      <XDSListItem
        label="Jordan Lee"
        description="Can you review the design spec when you get a chance?"
        startContent={<XDSAvatar name="Jordan Lee" size={40} />}
        onClick={() => {}}
        endContent={<XDSBadge label="5" />}
      />
    </XDSList>
  );
}

List — Ordered StepsNumbered step-by-step instructions using decimal list markers.

tsx
'use client';
import {XDSList, XDSListItem} from '@xds/core/List';
export default function ListOrderedSteps() {
  return (
    <XDSList listStyle="decimal">
      <XDSListItem
        label="Install the package"
        description="npm install @xds/core"
      />
      <XDSListItem
        label="Import components"
        description="import { XDSList } from '@xds/core'"
      />
      <XDSListItem
        label="Start building"
        description="Use components in your app"
      />
    </XDSList>
  );
}

Showcase source

tsx
'use client';
import {XDSList, XDSListItem} from '@xds/core/List';
export default function ListShowcase() {
  return (
    <XDSList>
      <XDSListItem label="Notifications" description="Manage your alerts" />
      <XDSListItem label="Privacy" description="Control your data" />
      <XDSListItem label="Security" description="Password and 2FA" />
    </XDSList>
  );
}