ListItem

Functions summary

`Unit`	`@Composable ListItem( headlineContent: @Composable () -> Unit, modifier: Modifier, overlineContent: (@Composable () -> Unit)?, supportingContent: (@Composable () -> Unit)?, leadingContent: (@Composable () -> Unit)?, trailingContent: (@Composable () -> Unit)?, colors: ListItemColors, tonalElevation: Dp, shadowElevation: Dp )` Material Design list item	Cmn
`Unit`	@ExperimentalMaterial3ExpressiveApi @Composable ListItem( onClick: () -> Unit, modifier: Modifier, enabled: Boolean, leadingContent: (@Composable () -> Unit)?, trailingContent: (@Composable () -> Unit)?, overlineContent: (@Composable () -> Unit)?, supportingContent: (@Composable () -> Unit)?, verticalAlignment: Alignment.Vertical, onLongClick: (() -> Unit)?, onLongClickLabel: String?, shapes: ListItemShapes, colors: ListItemColors, elevation: ListItemElevation, contentPadding: PaddingValues, interactionSource: MutableInteractionSource?, content: @Composable () -> Unit ) Material Design standard list item	Cmn
`Unit`	@ExperimentalMaterial3ExpressiveApi @Composable ListItem( checked: Boolean, onCheckedChange: (Boolean) -> Unit, modifier: Modifier, enabled: Boolean, leadingContent: (@Composable () -> Unit)?, trailingContent: (@Composable () -> Unit)?, overlineContent: (@Composable () -> Unit)?, supportingContent: (@Composable () -> Unit)?, verticalAlignment: Alignment.Vertical, onLongClick: (() -> Unit)?, onLongClickLabel: String?, shapes: ListItemShapes, colors: ListItemColors, elevation: ListItemElevation, contentPadding: PaddingValues, interactionSource: MutableInteractionSource?, content: @Composable () -> Unit ) Material Design standard list item	Cmn
`Unit`	@ExperimentalMaterial3ExpressiveApi @Composable ListItem( selected: Boolean, onClick: () -> Unit, modifier: Modifier, enabled: Boolean, leadingContent: (@Composable () -> Unit)?, trailingContent: (@Composable () -> Unit)?, overlineContent: (@Composable () -> Unit)?, supportingContent: (@Composable () -> Unit)?, verticalAlignment: Alignment.Vertical, onLongClick: (() -> Unit)?, onLongClickLabel: String?, shapes: ListItemShapes, colors: ListItemColors, elevation: ListItemElevation, contentPadding: PaddingValues, interactionSource: MutableInteractionSource?, content: @Composable () -> Unit ) Material Design standard list item	Cmn

Functions

ListItem

Cmn

Artifact: androidx.compose.material3:material3

View Source

Added in 1.5.0-alpha16

@Composable
fun ListItem(
    headlineContent: @Composable () -> Unit,
    modifier: Modifier = Modifier,
    overlineContent: (@Composable () -> Unit)? = null,
    supportingContent: (@Composable () -> Unit)? = null,
    leadingContent: (@Composable () -> Unit)? = null,
    trailingContent: (@Composable () -> Unit)? = null,
    colors: ListItemColors = ListItemDefaults.colors(),
    tonalElevation: Dp = ListItemDefaults.Elevation,
    shadowElevation: Dp = ListItemDefaults.Elevation
): Unit

Material Design list item

Lists are continuous, vertical indexes of text or images.

This overload of list item does not handle any user interaction. See other overloads for handling general click actions, single-selection, or multi-selection.

Lists
image

This component can be used to achieve the list item templates existing in the spec. One-line list items have a singular line of headline content. Two-line list items additionally have either supporting or overline content. Three-line list items have either both supporting and overline content, or extended (two-line) supporting text. For example:

one-line item

import androidx.compose.foundation.layout.Column
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text

Column {
    HorizontalDivider()
    ListItem(
        headlineContent = { Text("One line list item with 24x24 icon") },
        leadingContent = {
            Icon(Icons.Filled.Favorite, contentDescription = "Localized description")
        },
    )
    HorizontalDivider()
}

two-line item

import androidx.compose.foundation.layout.Column
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text

Column {
    HorizontalDivider()
    ListItem(
        headlineContent = { Text("Two line list item with trailing") },
        supportingContent = { Text("Secondary text") },
        trailingContent = { Text("meta") },
        leadingContent = {
            Icon(Icons.Filled.Favorite, contentDescription = "Localized description")
        },
    )
    HorizontalDivider()
}

three-line item with both overline and supporting content

import androidx.compose.foundation.layout.Column
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text

Column {
    HorizontalDivider()
    ListItem(
        headlineContent = { Text("Three line list item") },
        overlineContent = { Text("OVERLINE") },
        supportingContent = { Text("Secondary text") },
        leadingContent = {
            Icon(Icons.Filled.Favorite, contentDescription = "Localized description")
        },
        trailingContent = { Text("meta") },
    )
    HorizontalDivider()
}

three-line item with extended supporting content

import androidx.compose.foundation.layout.Column
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text

Column {
    HorizontalDivider()
    ListItem(
        headlineContent = { Text("Three line list item") },
        supportingContent = { Text("Secondary text that\nspans multiple lines") },
        leadingContent = {
            Icon(Icons.Filled.Favorite, contentDescription = "Localized description")
        },
        trailingContent = { Text("meta") },
    )
    HorizontalDivider()
}

Parameters
`headlineContent: @Composable () -> Unit`	the headline content of the list item
`modifier: Modifier = Modifier`	`Modifier` to be applied to the list item
`overlineContent: (@Composable () -> Unit)? = null`	the content displayed above the headline content
`supportingContent: (@Composable () -> Unit)? = null`	the supporting content of the list item
`leadingContent: (@Composable () -> Unit)? = null`	the leading content of the list item
`trailingContent: (@Composable () -> Unit)? = null`	the trailing meta text, icon, switch or checkbox
`colors: ListItemColors = ListItemDefaults.colors()`	`ListItemColors` that will be used to resolve the background and content color for this list item in different states. See `ListItemDefaults.colors`
`tonalElevation: Dp = ListItemDefaults.Elevation`	the tonal elevation of this list item
`shadowElevation: Dp = ListItemDefaults.Elevation`	the shadow elevation of this list item

ListItem

Cmn

Artifact: androidx.compose.material3:material3

View Source

Added in 1.5.0-alpha16

@ExperimentalMaterial3ExpressiveApi
@Composable
fun ListItem(
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    leadingContent: (@Composable () -> Unit)? = null,
    trailingContent: (@Composable () -> Unit)? = null,
    overlineContent: (@Composable () -> Unit)? = null,
    supportingContent: (@Composable () -> Unit)? = null,
    verticalAlignment: Alignment.Vertical = ListItemDefaults.verticalAlignment(),
    onLongClick: (() -> Unit)? = null,
    onLongClickLabel: String? = null,
    shapes: ListItemShapes = ListItemDefaults.shapes(),
    colors: ListItemColors = ListItemDefaults.colors(),
    elevation: ListItemElevation = ListItemDefaults.elevation(),
    contentPadding: PaddingValues = ListItemDefaults.ContentPadding,
    interactionSource: MutableInteractionSource? = null,
    content: @Composable () -> Unit
): Unit

Material Design standard list item

Lists are continuous, vertical indexes of text or images.

This overload of ListItem handles click events, calling its onClick lambda to trigger an action. See other overloads for handling single-selection, multi-selection, or no interaction handling.

import androidx.compose.foundation.layout.Column
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Home
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.saveable.rememberSaveable

Column {
    HorizontalDivider()

    repeat(3) { idx ->
        var count by rememberSaveable { mutableIntStateOf(0) }
        ListItem(
            onClick = { count++ },
            leadingContent = { Icon(Icons.Default.Home, contentDescription = null) },
            trailingContent = { Text("$count") },
            supportingContent = { Text("Additional info") },
            content = { Text("Item ${idx + 1}") },
        )

        HorizontalDivider()
    }
}

import androidx.compose.foundation.layout.Column
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material.icons.filled.Home
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text

Column {
    HorizontalDivider()

    repeat(3) { idx ->
        ListItem(
            onClick = { /* ListItem onClick callback */ },
            leadingContent = { Icon(Icons.Default.Home, contentDescription = null) },
            trailingContent = {
                IconButton(onClick = { /* Child onClick callback */ }) {
                    Icon(Icons.Default.Favorite, contentDescription = "Localized description")
                }
            },
            supportingContent = { Text("The trailing icon has a separate click action") },
            content = { Text("Item ${idx + 1}") },
        )

        HorizontalDivider()
    }
}

import androidx.compose.foundation.layout.Column
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material.icons.filled.Home
import androidx.compose.material3.Checkbox
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable

Column {
    HorizontalDivider()

    var inClickMode by rememberSaveable { mutableStateOf(true) }
    val counts = rememberSaveable { mutableStateListOf(0, 0, 0) }
    val checked = rememberSaveable { mutableStateListOf(false, false, false) }

    repeat(3) { idx ->
        if (inClickMode) {
            ListItem(
                onClick = { counts[idx]++ },
                onLongClick = {
                    checked[idx] = true
                    inClickMode = false
                },
                leadingContent = { Icon(Icons.Default.Home, contentDescription = null) },
                trailingContent = { Text("${counts[idx]}") },
                supportingContent = { Text("Long-click to change interaction mode.") },
                content = { Text("Item ${idx + 1}") },
            )
        } else {
            ListItem(
                checked = checked[idx],
                onCheckedChange = { checked[idx] = it },
                onLongClick = {
                    inClickMode = true
                    checked.clear()
                    checked.addAll(listOf(false, false, false))
                },
                leadingContent = { Checkbox(checked = checked[idx], onCheckedChange = null) },
                trailingContent = { Icon(Icons.Default.Favorite, contentDescription = null) },
                supportingContent = { Text("Long-click to change interaction mode.") },
                content = { Text("Item ${idx + 1}") },
            )
        }

        HorizontalDivider()
    }
}

Parameters
`onClick: () -> Unit`	called when this list item is clicked.
`modifier: Modifier = Modifier`	the `Modifier` to be applied to this list item.
`enabled: Boolean = true`	controls the enabled state of this list item. When `false`, this component will not respond to user input, and it will appear visually disabled and disabled to accessibility services.
`leadingContent: (@Composable () -> Unit)? = null`	the leading content of this list item, such as an icon or avatar.
`trailingContent: (@Composable () -> Unit)? = null`	the trailing content of this list item, such as a checkbox, switch, or icon.
`overlineContent: (@Composable () -> Unit)? = null`	the content displayed above the main content of the list item.
`supportingContent: (@Composable () -> Unit)? = null`	the content displayed below the main content of the list item.
`verticalAlignment: Alignment.Vertical = ListItemDefaults.verticalAlignment()`	the vertical alignment of children within the list item, after accounting for `contentPadding`.
`onLongClick: (() -> Unit)? = null`	called when this list item is long clicked (long-pressed).
`onLongClickLabel: String? = null`	semantic / accessibility label for the `onLongClick` action.
`shapes: ListItemShapes = ListItemDefaults.shapes()`	the `ListItemShapes` that this list item will use to morph between depending on the user's interaction with the list item. See `ListItemDefaults.shapes`.
`colors: ListItemColors = ListItemDefaults.colors()`	the `ListItemColors` that will be used to resolve the colors used for this list item in different states. See `ListItemDefaults.colors`.
`elevation: ListItemElevation = ListItemDefaults.elevation()`	the `ListItemElevation` used to resolve the elevation for this list item in different states. See `ListItemDefaults.elevation`.
`contentPadding: PaddingValues = ListItemDefaults.ContentPadding`	the padding to be applied to the content of this list item.
`interactionSource: MutableInteractionSource? = null`	an optional hoisted `MutableInteractionSource` for observing and emitting `Interaction`s for this list item. You can use this to change the list item's appearance or preview the list item in different states. Note that if `null` is provided, interactions will still happen internally.
`content: @Composable () -> Unit`	the main content of this list item. Also known as the headline or label.

ListItem

Cmn

Artifact: androidx.compose.material3:material3

View Source

@ExperimentalMaterial3ExpressiveApi
@Composable
fun ListItem(
    checked: Boolean,
    onCheckedChange: (Boolean) -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    leadingContent: (@Composable () -> Unit)? = null,
    trailingContent: (@Composable () -> Unit)? = null,
    overlineContent: (@Composable () -> Unit)? = null,
    supportingContent: (@Composable () -> Unit)? = null,
    verticalAlignment: Alignment.Vertical = ListItemDefaults.verticalAlignment(),
    onLongClick: (() -> Unit)? = null,
    onLongClickLabel: String? = null,
    shapes: ListItemShapes = ListItemDefaults.shapes(),
    colors: ListItemColors = ListItemDefaults.colors(),
    elevation: ListItemElevation = ListItemDefaults.elevation(),
    contentPadding: PaddingValues = ListItemDefaults.ContentPadding,
    interactionSource: MutableInteractionSource? = null,
    content: @Composable () -> Unit
): Unit

Material Design standard list item

Lists are continuous, vertical indexes of text or images.

This overload of ListItem represents a multi-selection (toggleable) item, analogous to a Checkbox. See other overloads for handling general click actions, single-selection, or no interaction handling.

import androidx.compose.foundation.layout.Column
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material3.Checkbox
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable

Column {
    HorizontalDivider()

    repeat(3) { idx ->
        var checked by rememberSaveable { mutableStateOf(false) }
        ListItem(
            checked = checked,
            onCheckedChange = { checked = it },
            leadingContent = { Checkbox(checked = checked, onCheckedChange = null) },
            trailingContent = { Icon(Icons.Default.Favorite, contentDescription = null) },
            supportingContent = { Text("Additional info") },
            content = { Text("Item ${idx + 1}") },
        )

        HorizontalDivider()
    }
}

import androidx.compose.foundation.layout.Column
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material.icons.filled.Home
import androidx.compose.material3.Checkbox
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable

Column {
    HorizontalDivider()

    var inClickMode by rememberSaveable { mutableStateOf(true) }
    val counts = rememberSaveable { mutableStateListOf(0, 0, 0) }
    val checked = rememberSaveable { mutableStateListOf(false, false, false) }

    repeat(3) { idx ->
        if (inClickMode) {
            ListItem(
                onClick = { counts[idx]++ },
                onLongClick = {
                    checked[idx] = true
                    inClickMode = false
                },
                leadingContent = { Icon(Icons.Default.Home, contentDescription = null) },
                trailingContent = { Text("${counts[idx]}") },
                supportingContent = { Text("Long-click to change interaction mode.") },
                content = { Text("Item ${idx + 1}") },
            )
        } else {
            ListItem(
                checked = checked[idx],
                onCheckedChange = { checked[idx] = it },
                onLongClick = {
                    inClickMode = true
                    checked.clear()
                    checked.addAll(listOf(false, false, false))
                },
                leadingContent = { Checkbox(checked = checked[idx], onCheckedChange = null) },
                trailingContent = { Icon(Icons.Default.Favorite, contentDescription = null) },
                supportingContent = { Text("Long-click to change interaction mode.") },
                content = { Text("Item ${idx + 1}") },
            )
        }

        HorizontalDivider()
    }
}

Parameters
`checked: Boolean`	whether this list item is toggled on or off.
`onCheckedChange: (Boolean) -> Unit`	called when this toggleable list item is clicked.
`modifier: Modifier = Modifier`	the `Modifier` to be applied to this list item.
`enabled: Boolean = true`	controls the enabled state of this list item. When `false`, this component will not respond to user input, and it will appear visually disabled and disabled to accessibility services.
`leadingContent: (@Composable () -> Unit)? = null`	the leading content of this list item, such as an icon or avatar.
`trailingContent: (@Composable () -> Unit)? = null`	the trailing content of this list item, such as a checkbox, switch, or icon.
`overlineContent: (@Composable () -> Unit)? = null`	the content displayed above the main content of the list item.
`supportingContent: (@Composable () -> Unit)? = null`	the content displayed below the main content of the list item.
`verticalAlignment: Alignment.Vertical = ListItemDefaults.verticalAlignment()`	the vertical alignment of children within the list item, after accounting for `contentPadding`.
`onLongClick: (() -> Unit)? = null`	called when this list item is long clicked (long-pressed).
`onLongClickLabel: String? = null`	semantic / accessibility label for the `onLongClick` action.
`shapes: ListItemShapes = ListItemDefaults.shapes()`	the `ListItemShapes` that this list item will use to morph between depending on the user's interaction with the list item. See `ListItemDefaults.shapes`.
`colors: ListItemColors = ListItemDefaults.colors()`	the `ListItemColors` that will be used to resolve the colors used for this list item in different states. See `ListItemDefaults.colors`.
`elevation: ListItemElevation = ListItemDefaults.elevation()`	the `ListItemElevation` used to resolve the elevation for this list item in different states. See `ListItemDefaults.elevation`.
`contentPadding: PaddingValues = ListItemDefaults.ContentPadding`	the padding to be applied to the content of this list item.
`interactionSource: MutableInteractionSource? = null`	an optional hoisted `MutableInteractionSource` for observing and emitting `Interaction`s for this list item. You can use this to change the list item's appearance or preview the list item in different states. Note that if `null` is provided, interactions will still happen internally.
`content: @Composable () -> Unit`	the main content of this list item. Also known as the headline or label.

ListItem

Cmn

Artifact: androidx.compose.material3:material3

View Source

Added in 1.5.0-alpha16

@ExperimentalMaterial3ExpressiveApi
@Composable
fun ListItem(
    selected: Boolean,
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    leadingContent: (@Composable () -> Unit)? = null,
    trailingContent: (@Composable () -> Unit)? = null,
    overlineContent: (@Composable () -> Unit)? = null,
    supportingContent: (@Composable () -> Unit)? = null,
    verticalAlignment: Alignment.Vertical = ListItemDefaults.verticalAlignment(),
    onLongClick: (() -> Unit)? = null,
    onLongClickLabel: String? = null,
    shapes: ListItemShapes = ListItemDefaults.shapes(),
    colors: ListItemColors = ListItemDefaults.colors(),
    elevation: ListItemElevation = ListItemDefaults.elevation(),
    contentPadding: PaddingValues = ListItemDefaults.ContentPadding,
    interactionSource: MutableInteractionSource? = null,
    content: @Composable () -> Unit
): Unit

Material Design standard list item

Lists are continuous, vertical indexes of text or images.

This overload of ListItem represents a single-selection item, analogous to a RadioButton. See other overloads for handling general click actions, multi-selection, or no interaction handling.

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.selection.selectableGroup
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.RadioButton
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.Modifier

Column(Modifier.selectableGroup()) {
    HorizontalDivider()

    var selectedIndex: Int? by rememberSaveable { mutableStateOf(null) }
    repeat(3) { idx ->
        val selected = selectedIndex == idx
        ListItem(
            selected = selected,
            onClick = { selectedIndex = if (selected) null else idx },
            leadingContent = { RadioButton(selected = selected, onClick = null) },
            trailingContent = { Icon(Icons.Default.Favorite, contentDescription = null) },
            supportingContent = { Text("Additional info") },
            content = { Text("Item ${idx + 1}") },
        )

        HorizontalDivider()
    }
}

Parameters
`selected: Boolean`	whether or not this list item is selected.
`onClick: () -> Unit`	called when this list item is clicked.
`modifier: Modifier = Modifier`	the `Modifier` to be applied to this list item.
`enabled: Boolean = true`	controls the enabled state of this list item. When `false`, this component will not respond to user input, and it will appear visually disabled and disabled to accessibility services.
`leadingContent: (@Composable () -> Unit)? = null`	the leading content of this list item, such as an icon or avatar.
`trailingContent: (@Composable () -> Unit)? = null`	the trailing content of this list item, such as a checkbox, switch, or icon.
`overlineContent: (@Composable () -> Unit)? = null`	the content displayed above the main content of the list item.
`supportingContent: (@Composable () -> Unit)? = null`	the content displayed below the main content of the list item.
`verticalAlignment: Alignment.Vertical = ListItemDefaults.verticalAlignment()`	the vertical alignment of children within the list item, after accounting for `contentPadding`.
`onLongClick: (() -> Unit)? = null`	called when this list item is long clicked (long-pressed).
`onLongClickLabel: String? = null`	semantic / accessibility label for the `onLongClick` action.
`shapes: ListItemShapes = ListItemDefaults.shapes()`	the `ListItemShapes` that this list item will use to morph between depending on the user's interaction with the list item. See `ListItemDefaults.shapes`.
`colors: ListItemColors = ListItemDefaults.colors()`	the `ListItemColors` that will be used to resolve the colors used for this list item in different states. See `ListItemDefaults.colors`.
`elevation: ListItemElevation = ListItemDefaults.elevation()`	the `ListItemElevation` used to resolve the elevation for this list item in different states. See `ListItemDefaults.elevation`.
`contentPadding: PaddingValues = ListItemDefaults.ContentPadding`	the padding to be applied to the content of this list item.
`interactionSource: MutableInteractionSource? = null`	an optional hoisted `MutableInteractionSource` for observing and emitting `Interaction`s for this list item. You can use this to change the list item's appearance or preview the list item in different states. Note that if `null` is provided, interactions will still happen internally.
`content: @Composable () -> Unit`	the main content of this list item. Also known as the headline or label.