# 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

```kotlin
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.

```kotlin
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.

## Related components

- [Card](https://m3e.ljzapps.app/docs/components/card.md)
- [Divider](https://m3e.ljzapps.app/docs/components/divider.md)
- [Menu](https://m3e.ljzapps.app/docs/components/menu.md)