XDS — Design System

List@xds/core · XDSList v0.0.13

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.

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

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.

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>
  );
}

Usage

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

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.

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={{}}.

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.

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> ); }

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> ); }

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> ); }

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> ); }

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> ); }