ListItem

Functions summary

Unit
@Composable
@ExperimentalMaterialApi
ListItem(
    modifier: Modifier,
    icon: (@Composable () -> Unit)?,
    secondaryText: (@Composable () -> Unit)?,
    singleLineSecondaryText: Boolean,
    overlineText: (@Composable () -> Unit)?,
    trailing: (@Composable () -> Unit)?,
    text: @Composable () -> Unit
)

Material Design list
Cmn

Functions

ListItem

Cmn 
@Composable
@ExperimentalMaterialApi
fun ListItem(
    modifier: Modifier = Modifier,
    icon: (@Composable () -> Unit)? = null,
    secondaryText: (@Composable () -> Unit)? = null,
    singleLineSecondaryText: Boolean = true,
    overlineText: (@Composable () -> Unit)? = null,
    trailing: (@Composable () -> Unit)? = null,
    text: @Composable () -> Unit
): Unit

Material Design list

Lists are continuous, vertical indexes of text or images.

Lists image

To make this ListItem clickable, use androidx.compose.foundation.clickable. To add a background to the ListItem, wrap it with a Surface.

This component can be used to achieve the list item templates existing in the spec. For example:

  • one-line items

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.size
import androidx.compose.material.Divider
import androidx.compose.material.Icon
import androidx.compose.material.ListItem
import androidx.compose.material.Text
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

Column {
    ListItem(text = { Text("One line list item with no icon") })
    Divider()
    ListItem(
        text = { Text("One line list item with 24x24 icon") },
        icon = { Icon(Icons.Filled.Favorite, contentDescription = null) },
    )
    Divider()
    ListItem(
        text = { Text("One line list item with 40x40 icon") },
        icon = {
            Icon(
                Icons.Filled.Favorite,
                contentDescription = null,
                modifier = Modifier.size(40.dp),
            )
        },
    )
    Divider()
    ListItem(
        text = { Text("One line list item with 56x56 icon") },
        icon = {
            Icon(
                Icons.Filled.Favorite,
                contentDescription = null,
                modifier = Modifier.size(56.dp),
            )
        },
    )
    Divider()
    ListItem(
        text = { Text("One line clickable list item") },
        icon = {
            Icon(
                Icons.Filled.Favorite,
                contentDescription = null,
                modifier = Modifier.size(56.dp),
            )
        },
        modifier = Modifier.clickable {},
    )
    Divider()
    ListItem(
        text = { Text("One line list item with trailing icon") },
        trailing = { Icon(Icons.Filled.Favorite, contentDescription = "Localized Description") },
    )
    Divider()
    ListItem(
        text = { Text("One line list item") },
        icon = {
            Icon(
                Icons.Filled.Favorite,
                contentDescription = null,
                modifier = Modifier.size(40.dp),
            )
        },
        trailing = { Icon(Icons.Filled.Favorite, contentDescription = "Localized description") },
    )
    Divider()
}

  • two-line items

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.size
import androidx.compose.material.Divider
import androidx.compose.material.Icon
import androidx.compose.material.ListItem
import androidx.compose.material.Text
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

Column {
    ListItem(text = { Text("Two line list item") }, secondaryText = { Text("Secondary text") })
    Divider()
    ListItem(text = { Text("Two line list item") }, overlineText = { Text("OVERLINE") })
    Divider()
    ListItem(
        text = { Text("Two line list item with 24x24 icon") },
        secondaryText = { Text("Secondary text") },
        icon = { Icon(Icons.Filled.Favorite, contentDescription = null) },
    )
    Divider()
    ListItem(
        text = { Text("Two line list item with 40x40 icon") },
        secondaryText = { Text("Secondary text") },
        icon = {
            Icon(
                Icons.Filled.Favorite,
                contentDescription = null,
                modifier = Modifier.size(40.dp),
            )
        },
    )
    Divider()
    ListItem(
        text = { Text("Two line list item with 40x40 icon") },
        secondaryText = { Text("Secondary text") },
        trailing = { Text("meta") },
        icon = {
            Icon(
                Icons.Filled.Favorite,
                contentDescription = null,
                modifier = Modifier.size(40.dp),
            )
        },
    )
    Divider()
}

  • three-line items

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

Column {
    ListItem(
        text = { Text("Three line list item") },
        secondaryText = {
            Text(
                "This is a long secondary text for the current list item, " +
                    "displayed on two lines"
            )
        },
        singleLineSecondaryText = false,
        trailing = { Text("meta") },
    )
    Divider()
    ListItem(
        text = { Text("Three line list item") },
        overlineText = { Text("OVERLINE") },
        secondaryText = { Text("Secondary text") },
    )
    Divider()
    ListItem(
        text = { Text("Three line list item with 24x24 icon") },
        secondaryText = {
            Text(
                "This is a long secondary text for the current list item " +
                    "displayed on two lines"
            )
        },
        singleLineSecondaryText = false,
        icon = { Icon(Icons.Filled.Favorite, contentDescription = null) },
    )
    Divider()
    ListItem(
        text = { Text("Three line list item with trailing icon") },
        secondaryText = {
            Text(
                "This is a long secondary text for the current list" +
                    " item, displayed on two lines"
            )
        },
        singleLineSecondaryText = false,
        trailing = { Icon(Icons.Filled.Favorite, contentDescription = "Localized description") },
    )
    Divider()
    ListItem(
        text = { Text("Three line list item") },
        overlineText = { Text("OVERLINE") },
        secondaryText = { Text("Secondary text") },
        trailing = { Text("meta") },
    )
    Divider()
}

You can combine this component with a checkbox or switch as in the following examples:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.selection.toggleable
import androidx.compose.material.Checkbox
import androidx.compose.material.Divider
import androidx.compose.material.ListItem
import androidx.compose.material.Switch
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.semantics.Role

Column {
    var switched by remember { mutableStateOf(false) }
    val onSwitchedChange: (Boolean) -> Unit = { switched = it }
    ListItem(
        text = { Text("Switch ListItem") },
        trailing = {
            Switch(
                checked = switched,
                onCheckedChange = null, // null recommended for accessibility with screenreaders
            )
        },
        modifier =
            Modifier.toggleable(
                role = Role.Switch,
                value = switched,
                onValueChange = onSwitchedChange,
            ),
    )
    Divider()
    var checked by remember { mutableStateOf(true) }
    val onCheckedChange: (Boolean) -> Unit = { checked = it }
    ListItem(
        text = { Text("Checkbox ListItem") },
        trailing = {
            Checkbox(
                checked = checked,
                onCheckedChange = null, // null recommended for accessibility with screenreaders
            )
        },
        modifier =
            Modifier.toggleable(
                role = Role.Checkbox,
                value = checked,
                onValueChange = onCheckedChange,
            ),
    )
    Divider()
}
Parameters
modifier: Modifier = Modifier

Modifier to be applied to the list item
icon: (@Composable () -> Unit)? = null

The leading supporting visual of the list item
secondaryText: (@Composable () -> Unit)? = null

The secondary text of the list item
singleLineSecondaryText: Boolean = true

Whether the secondary text is single line
overlineText: (@Composable () -> Unit)? = null

The text displayed above the primary text
trailing: (@Composable () -> Unit)? = null

The trailing meta text, icon, switch or checkbox
text: @Composable () -> Unit

The primary text of the list item