List

Rows of related content with optional icons, supporting text and trailing controls.

Category: Containment
API status: Expressive
Compose APIs: ListItem, SegmentedListItem, ListItemDefaults
Interactive page: https://m3e.ljzapps.app/#components/list

When to use

ListItem supports up to three lines with an overline, headline and supporting text, plus leading and trailing content. Clickable, selectable and checkable overloads share the same layout.

Segmented list items are the Expressive style. Each item is a separate rounded container with a small gap, and the first and last items have larger outer corners.

Playground

The interactive page has a playground with live property controls for this component and generated code.

Examples

Segmented, selectable

val names = listOf("Maya Chen", "Jonas Weber", "Ana Silva", "Kenji Sato")
var selected by rememberSaveable { mutableIntStateOf(0) }

Column(
    modifier = Modifier.widthIn(max = 420.dp).fillMaxWidth(),
    verticalArrangement = Arrangement.spacedBy(ListItemDefaults.SegmentedGap),
) {
    names.forEachIndexed { index, name ->
        SegmentedListItem(
            selected = selected == index,
            onClick = { selected = index },
            shapes = ListItemDefaults.segmentedShapes(index = index, count = names.size),
            leadingContent = { Icon(Icons.Rounded.Person, contentDescription = null) },
            supportingContent = { Text("Last active ${index + 1} h ago") },
        ) {
            Text(name)
        }
    }
}

Checkable

The whole row toggles.

val items = listOf("Wi-Fi", "Bluetooth", "Location")
var checked by remember { mutableStateOf(setOf("Wi-Fi")) }

Column(Modifier.widthIn(max = 420.dp).fillMaxWidth()) {
    items.forEach { item ->
        ListItem(
            checked = item in checked,
            onCheckedChange = { isChecked -> checked = if (isChecked) checked + item else checked - item },
            trailingContent = { Checkbox(checked = item in checked, onCheckedChange = null) },
        ) {
            Text(item)
        }
    }
}

Parameters

Name	Type	Default	Description
`headlineContent`	`@Composable () -> Unit`		Main text. In the clickable overloads this is the trailing content lambda.
`supportingContent`	`@Composable (() -> Unit)?`	`null`	Secondary text.
`overlineContent`	`@Composable (() -> Unit)?`	`null`	Small text above the headline.
`leadingContent / trailingContent`	`@Composable (() -> Unit)?`	`null`	Icons, avatars or controls.
`shapes`	`ListItemShapes`	`ListItemDefaults.shapes()`	Interactive overloads. Use segmentedShapes(index, count).

Guidelines

Do:

Keep the headline to one line.
Align leading elements.

Don't:

Do not mix one, two and three line items in a list.
Do not use more than one trailing control.

Accessibility

Interactive rows merge their content into one focus target.
Do not nest a separate button in a clickable row, put the action in the trailing content only when it is a different action.