CONTENT DISPLAY

List

Draft

A semantic list component for rendering structured rows of content with support for headings, descriptions, and artwork.

Usage

• Jane Doe

  Software Engineer
• Alex Kim

  Product Designer
• Sam Lee

  Engineering Manager
• Pat Chen

  Data Scientist

Common alternative names

Collection, Item list

---

Anatomy

A list item supports a wide range of leading and trailing content configurations. The diagram below shows every possible slot combination available to list items.

Leading content

Trailing content

Avatar / Image

• LT
  Label text

  Description

Radio

Badge

• 3
  Label text

  Description

Checkbox

Large icon

• Label text

  Description

Toggle

Medium icon

• Label text

  Description
  1

Stepper

Small icon

• Label text

Icon buttons

Up to 3 lines
of text

• Label text

  Description line one
  Description line two

Text button

• Label text

  Description

Chevron

• Label text

  Description
  Value

  Subtext

Text lines

• Label text

  Description
  New

Badge

Usage guidelines coming soon.

Specs

Specs coming soon.

Content

Content guidelines coming soon.

Status & changelog

Status & changelog coming soon.

Code

---

Usage

Basic list

import { List, ListItem, ListItemLabel } from '@arch-ui/components';

<List>
  <ListItem>
    <ListItemLabel description="Software Engineer">Jane Doe</ListItemLabel>
  </ListItem>
  <ListItem>
    <ListItemLabel description="Product Designer">Alex Kim</ListItemLabel>
  </ListItem>
</List>

---

With artwork and end enhancer

<List>
  <ListItem
    artwork={<Avatar name="Jane Doe" size="small" />}
    artworkSize="small"
    endEnhancer={<span>3m ago</span>}
  >
    <ListItemLabel description="Sent you a message">Jane Doe</ListItemLabel>
  </ListItem>
</List>

---

List variants

Control the list marker style with variant.

<List variant="bullet">
  <li>Unordered item one</li>
  <li>Unordered item two</li>
</List>

<List variant="number">
  <li>First step</li>
  <li>Second step</li>
</List>

<List variant="none">
  <ListItem>No markers</ListItem>
</List>

---

Section headings

Use ListHeading to label groups within a list.

<List>
  <ListHeading heading="Team members" subHeading="3 people" />
  <ListItem><ListItemLabel>Jane</ListItemLabel></ListItem>
  <ListItem><ListItemLabel>Alex</ListItemLabel></ListItem>
  <ListItem><ListItemLabel>Sam</ListItemLabel></ListItem>
</List>

---

Description list

For key-value pairs, use the DescriptionList components.

import { DescriptionList, DescriptionTerm, DescriptionDetail } from '@arch-ui/components';

<DescriptionList>
  <DescriptionTerm>Name</DescriptionTerm>
  <DescriptionDetail>Jane Doe</DescriptionDetail>
  <DescriptionTerm>Role</DescriptionTerm>
  <DescriptionDetail>Engineer</DescriptionDetail>
</DescriptionList>

---

Props

ListProps

Prop	Type	Default	Description
variant	'bullet' | 'number' | 'none'	'none'	Visual style of list markers.
as	'ul' | 'ol'	auto	Override the rendered element. Auto-selects <ol> for number, <ul> otherwise.
children	ReactNode	--	List content.
className	string	--	Additional CSS class names.

---

ListHeadingProps

Prop	Type	Default	Description
heading	ReactNode	required	Heading text.
subHeading	ReactNode	--	Sub-heading text.
endEnhancer	ReactNode	--	Content on the right side.
endEnhancerDescription	ReactNode	--	Description below the end enhancer.
maxLines	1 | 2	1	Max lines for heading text. 1 enables ellipsis truncation.
className	string	--	Additional CSS class names.

---

Sub-components

List exports several companion components:

• ListItem -- Rich list row with artwork, content, and end enhancer slots. See List Item.
• ListItemLabel -- Structured content block with primary label and description.
• ListHeading -- Section heading row for grouping items.
• DescriptionList / DescriptionTerm / DescriptionDetail -- Semantic <dl> pattern rendered as a two-column grid.

---

Accessibility

• Renders semantic <ul> or <ol> elements based on the variant.
• DescriptionList uses a native <dl> with <dt> and <dd> elements for proper semantics.
• Interactive ListItems receive role="button" and keyboard focus support.