List

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

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

    ClassDescription
    .listBase list container (required)
    .list-itemBase list item (required)
    .list-item-contentContent wrapper for text
    .list-item-textPrimary text content
    .list-item-secondarySecondary/supporting text
    .list-item-leadingLeading element (icon, avatar)
    .list-item-trailingTrailing element (icon, action)
    .list-item-interactiveAdds hover/active states
    .list-item-activeActive/selected state (primary)
    .list-item-active-primaryActive state with primary color
    .list-item-active-secondaryActive state with secondary color
    .list-item-active-tertiaryActive state with tertiary color
    .list-item-two-lineTwo-line list item variant
    .list-item-three-lineThree-line list item variant
    .list-dividerHorizontal divider line
    .list-divider-insetInset divider (with leading element)
    .list-subheaderSection subheader
    .list-compactCompact density variant
    .list-comfortableComfortable density variant
    .list-surface-containerContainer surface elevation
    .list-surface-container-lowLow container surface
    .list-surface-container-highHigh container surface
    .list-borderedAdd border to list
    .list-nestedNested/indented list
    .list-item-disabledDisabled 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