List

A continuous vertical index of text or images for displaying collections of items. Not intended for dense, multi-column data comparisons where tables are more appropriate.

Basic Usage

Simple one-line list items with headlines. Lists provide a scannable vertical rhythm for related records and actions. 

<ds-list>
  <ds-list-item headline="Item 1"></ds-list-item>
  <ds-list-item headline="Item 2"></ds-list-item>
</ds-list>

Initial Value

Pre-select items or populate supporting and trailing text.

<ds-list>
  <ds-list-item
    headline="Inbox"
    supporting-text="2 new messages"
    trailing-text="12:30 PM"
    selected>
  </ds-list-item>
</ds-list>

Variants

One-Line (Default)

Simple list items with only headline text.

Two-Line

List items with headline and supporting text.

Three-Line

List items with headline and longer supporting text (up to 2 lines).

With Leading Elements

List items with icons or avatars in the leading slot.

A
B
C

With Trailing Elements

List items with trailing text, buttons, or controls.

States

Selected and disabled list items.

Selected Items

Disabled Items

Interactive Example

Click items to select them. Try different variants.

Selected: None

API Reference

List Attributes

The <ds-list> container is a simple wrapper element.

List Item Attributes

Attribute Type Default Description
variant String "one-line" Item variant: "one-line", "two-line", or "three-line"
headline String - Primary text for the item
supporting-text String - Secondary text (two/three-line only)
trailing-text String - Optional trailing text
selected Boolean false Whether the item is selected
disabled Boolean false Whether the item is disabled

List Item Slots

Slot Description
leading Leading element (icon, avatar, checkbox)
trailing Trailing element (icon button, switch, checkbox)

List Item CSS Parts

Part Description
container The main item container
leading The leading slot container
content The content area with headline/supporting text
headline The headline text element
supporting-text The supporting text element
trailing The trailing slot container
trailing-text The trailing text element

List Item CSS Custom Properties

Property Description Default
--ds-list-item-height Height for one-line items calc(var(--ds-size-control-lg) + 8px)
--ds-list-item-height-two-line Height for two-line items calc(var(--ds-size-control-lg) + 24px)
--ds-list-item-height-three-line Height for three-line items calc(var(--ds-size-control-lg) + 40px)
--ds-list-item-padding Padding for the item container 8px 16px
--ds-list-item-border-color Divider color between items var(--md-sys-color-outline-variant)
--ds-list-item-leading-size Size for leading slot content var(--ds-size-hit-area)

List Item Events

Event Description
ds-list-item:click Fired when item is clicked (not fired if disabled)

Accessibility

Keyboard Interaction

Key Context Expected Result
Tab / Shift+Tab Interactive list content Moves focus to interactive elements within list items
Enter / Space Focus on interactive list item Activates the focused item if not disabled

Semantics

  • List uses role="list"; items use role="listitem".
  • Disabled items set aria-disabled="true" and suppress click events.
  • Focus management is preserved for interactive child controls.

Usage Guidelines

  • When to use: Use lists for related records, messages, settings, and selectable items in a vertical sequence.
  • When not to use: Avoid list layouts for dense comparative datasets that require columns or numeric alignment.
  • Composition: Use one-line, two-line, or three-line items consistently within a section and pair leading/trailing elements with clear purpose.
  • Common mistakes: Mixing item heights excessively and overloading trailing controls reduces scanability.