List

Material Design 3 list component for displaying organized content with support for icons, avatars, and multiple line variants

Canonical Composition And Compatibility

Use list-item-content, list-item-title, list-item-subtitle, list-item-icon and list-item-action. Historical list-item-text / list-item-secondary map to title/subtitle. list-item-leading / list-item-trailing remain composable slots; two/three-line items, surface variants, comfortable spacing and nested indentation are shipped. Text wraps in narrow containers and indentation follows RTL.

Use native links/buttons for interactive items. list-item-interactive and list-item-clickable only style a hook: they do not make a li into a keyboard control. Selection, ARIA and callbacks belong to the application. Status can be composed with visible labels; see Indicator.

List

Lists are continuous, vertical indexes of text or images. They present multiple line items in a vertical arrangement as a single connected element.

Basic Usage

Basic List

  • List Item 1
  • List Item 2
  • List Item 3

List Items

Simple List Items

Basic single-line list items:

Simple List Items

  • Photos
  • Videos
  • Documents

Two-Line List Items

List items with primary and secondary text:

Two-Line List Items

  • Brunch this weekend? Ali Connors — I'll be in your neighborhood
  • Summer BBQ to Alex, Scott, Jennifer — Wish I could come

Three-Line List Items

List items with expanded secondary text:

Three-Line List Items

  • Oui Oui Sandra Adams — Do you have Paris recommendations? Have you ever been? I'm looking for ideas for our upcoming trip.
  • Birthday Gift Trevor Hansen — Have any ideas about what we should get for the party? I was thinking about getting a board game.

Interactive Lists

Clickable List Items

Add hover and active states to list items:

Clickable List Items

  • Inbox
  • Starred
  • Sent Mail

Selected List Items

Show selected state with primary color:

Selected List Items

  • Inbox
  • Starred
  • Sent Mail

Active State Variants

Use different color schemes for selected items:

Active State Variants

  • Primary Selected
  • Secondary Selected
  • Tertiary Selected

    • List Items with Icons

    Leading Icons

    Add icons to the start of list items:

    List Items with Leading Icons

    • Inbox
    • Starred
    • Sent

    Trailing Icons

    Add icons or actions to the end of list items:

    List Items with Trailing Icons

    • Notifications
    • Privacy

    Both Leading and Trailing Elements

    Combine leading and trailing elements:

    Leading and Trailing Elements

    • Brunch this weekend? Ali Connors
      10:30 AM

    List Items with Avatars

    Use avatars for user-centric lists:

    List Items with Avatars

    • Ali Connors
      Ali Connors Brunch this weekend?
    • Jennifer Smith
      Jennifer Smith Dinner reservations

    List Dividers

    Standard Dividers

    Separate list items with dividers:

    Standard Dividers

    • Item 1
    • Item 2
    • Item 3

    Inset Dividers

    Use inset dividers for lists with leading elements:

    Inset Dividers

    • John Doe
    • Jane Smith

    List Subheaders

    Organize lists with subheaders:

    List Subheaders

      Today
    • Meeting with team 10:00 AM - 11:00 AM
    • Lunch break 12:00 PM - 1:00 PM
      • Tomorrow
    • Project review 9:00 AM - 10:00 AM

    List Density

    Compact Lists

    More condensed spacing for data-dense interfaces:

    Compact Lists

    • Compact Item 1
    • Compact Item 2

    Comfortable Lists

    More spacious for better readability:

    Comfortable Lists

    • Documents
    • Images

    Surface Variants

    Container Surfaces

    Apply different surface elevations:

    Container Surfaces

    • Default Surface
    • Container Surface
    • Container Low Surface
    • Container High Surface

    Bordered Lists

    Add borders to lists:

    Bordered Lists

    • Bordered Item 1
    • Bordered Item 2
    • Bordered Item 3

    Nested Lists

    Create hierarchical list structures:

    Nested Lists

    • Projects
      • Website Redesign
      • Mobile App
    • Team

    Disabled State

    Disable interaction with list items:

    Disabled List Items

    • Available Item
    • Disabled Item
    • Available Item

    Best Practices

    Content Organization

    • Use subheaders to group related list items
    • Keep list item text concise and scannable
    • Use two-line and three-line variants for additional context
    • Place the most important information in the primary text

    Visual Hierarchy

    Visual Hierarchy Best Practice

    • Featured Item This is the active selection
    • Standard Item
    • Unavailable Item

    Accessibility

    • Use semantic HTML (<ul>, <li>) for proper structure
    • Provide meaningful alt text for avatars and images
    • Ensure interactive items are keyboard accessible
    • Use aria-label for icon-only actions

    Accessible List Example

    • User profile picture
      John Doe Online

    Touch Targets

    Ensure list items are large enough for touch interaction:

    • Default list items: 48px minimum height
    • Two-line items: 64px minimum height
    • Three-line items: 88px minimum height
    • Use .list-comfortable for more generous touch targets

    Framework Examples

    React

    interface ListItemProps {
  primary: string;
  secondary?: string;
  icon?: React.ReactNode;
  avatar?: string;
  active?: boolean;
  interactive?: boolean;
  onClick?: () => void;
}

export function ListItem({
  primary,
  secondary,
  icon,
  avatar,
  active = false,
  interactive = false,
  onClick
}: ListItemProps) {
  const classes = [
    'list-item',
    secondary && 'list-item-two-line',
    interactive && 'list-item-interactive',
    active && 'list-item-active'
  ].filter(Boolean).join(' ');

  return (
    <li className={classes} onClick={onClick}>
      {(icon || avatar) && (
        <div className="list-item-leading">
          {avatar ? (
            <img src={avatar} alt="" className="w-10 h-10 rounded-full" />
          ) : icon}
        </div>
      )}
      <div className="list-item-content">
        <span className="list-item-text">{primary}</span>
        {secondary && (
          <span className="list-item-secondary">{secondary}</span>
        )}
      </div>
    </li>
  );
}

// Usage
<ul className="list">
  <ListItem
    primary="Inbox"
    secondary="5 new messages"
    icon={<InboxIcon />}
    interactive
    active
  />
  <ListItem
    primary="Starred"
    icon={<StarIcon />}
    interactive
  />
</ul>

    Vue

    <template>
  <li :class="classes" @click="onClick">
    <div v-if="icon || avatar" class="list-item-leading">
      <img v-if="avatar" :src="avatar" alt="" class="w-10 h-10 rounded-full" />
      <slot v-else name="icon"></slot>
    </div>
    <div class="list-item-content">
      <span class="list-item-text">{{ primary }}</span>
      <span v-if="secondary" class="list-item-secondary">{{ secondary }}</span>
    </div>
    <div v-if="$slots.trailing" class="list-item-trailing">
      <slot name="trailing"></slot>
    </div>
  </li>
</template>

<script setup>
import { computed } from 'vue';

const props = defineProps({
  primary: String,
  secondary: String,
  avatar: String,
  active: Boolean,
  interactive: Boolean
});

const emit = defineEmits(['click']);

const classes = computed(() => [
  'list-item',
  props.secondary && 'list-item-two-line',
  props.interactive && 'list-item-interactive',
  props.active && 'list-item-active'
].filter(Boolean).join(' '));

const onClick = () => {
  if (props.interactive) {
    emit('click');
  }
};
</script>

<!-- Usage -->
<ul class="list">
  <ListItem
    primary="Inbox"
    secondary="5 new messages"
    :interactive="true"
    :active="true"
  >
    <template #icon>
      <InboxIcon />
    </template>
  </ListItem>
</ul>

    API Reference

    Class Names

    Class Description
    .list Base list container (required)
    .list-item Base list item (required)
    .list-item-content Content wrapper for text
    .list-item-text Primary text content
    .list-item-secondary Secondary/supporting text
    .list-item-leading Leading element (icon, avatar)
    .list-item-trailing Trailing element (icon, action)
    .list-item-interactive Adds hover/active states
    .list-item-active Active/selected state (primary)
    .list-item-active-primary Active state with primary color
    .list-item-active-secondary Active state with secondary color
    .list-item-active-tertiary Active state with tertiary color
    .list-item-two-line Two-line list item variant
    .list-item-three-line Three-line list item variant
    .list-divider Horizontal divider line
    .list-divider-inset Inset divider (with leading element)
    .list-subheader Section subheader
    .list-compact Compact density variant
    .list-comfortable Comfortable density variant
    .list-surface-container Container surface elevation
    .list-surface-container-low Low container surface
    .list-surface-container-high High container surface
    .list-bordered Add border to list
    .list-nested Nested/indented list
    .list-item-disabled Disabled list item

    CSS Custom Properties

    Lists use the Material Design 3 color tokens:

    • --color-surface - List background
    • --color-on-surface - List item text
    • --color-on-surface-variant - Secondary text
    • --color-outline-variant - Divider color
    • --color-primary-container - Active item background
    • --color-on-primary-container - Active item text
    • --color-secondary-container - Secondary active background
    • --color-tertiary-container - Tertiary active background
    • Avatar - User profile images
    • Icon - Icon system
    • Card - Container component
    • Menu - Contextual menus

    See Also