XDS — Design System

XDSListItem@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 {XDSListItem} from '@xds/core/List'

Props

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.

Showcase source

tsx
'use client';
import {XDSList, XDSListItem} from '@xds/core/List';
import {XDSBadge} from '@xds/core/Badge';
import {XDSIcon} from '@xds/core/Icon';
export default function ListItemShowcase() {
  return (
    <XDSList header="Settings" hasDividers>
      <XDSListItem
        label="Notifications"
        description="Push, email, and SMS alerts"
        startContent={<XDSIcon icon="info" />}
        endContent={<XDSBadge label="3 new" variant="blue" />}
        onClick={() => {}}
      />
      <XDSListItem
        label="Privacy"
        description="Manage data sharing preferences"
        startContent={<XDSIcon icon="eyeSlash" />}
        onClick={() => {}}
      />
      <XDSListItem
        label="Appearance"
        description="Theme, font size, and display"
        startContent={<XDSIcon icon="wrench" />}
        onClick={() => {}}
      />
      <XDSListItem
        label="Billing"
        description="Plans and payment methods"
        startContent={<XDSIcon icon="copy" />}
        endContent={<XDSBadge label="Pro" variant="purple" />}
        onClick={() => {}}
      />
    </XDSList>
  );
}