# ListItem

Common/AllAndroid/JVM

## Functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable @https://developer.android.com/reference/kotlin/androidx/compose/material/ExperimentalMaterialApi https://developer.android.com/reference/kotlin/androidx/compose/material/ListItem.composable#ListItem(androidx.compose.ui.Modifier,kotlin.Function0,kotlin.Function0,kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Function0)( modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, icon: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, secondaryText: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, singleLineSecondaryText: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, overlineText: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, trailing: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, text: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` [Material Design list](https://material.io/components/lists) | Cmn |

## Functions

### ListItem

Cmn Artifact: [androidx.compose.material:material](https://developer.android.com/jetpack/androidx/releases/compose-material) [View Source](https://cs.android.com/search?q=file:androidx/compose/material/ListItem.kt+function:ListItem) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-material#1.0.0)

```
@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](https://material.io/components/lists)

Lists are continuous, vertical indexes of text or images.

![Lists
image](https://developer.android.com/images/reference/androidx/compose/material/lists.png)

To make this `https://developer.android.com/reference/kotlin/androidx/compose/material/ListItem.composable#ListItem(androidx.compose.ui.Modifier,kotlin.Function0,kotlin.Function0,kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Function0)` clickable, use `https://developer.android.com/reference/kotlin/androidx/compose/foundation/clickable.modifier#(androidx.compose.ui.Modifier).clickable(kotlin.Boolean,kotlin.String,androidx.compose.ui.semantics.Role,androidx.compose.foundation.interaction.MutableInteractionSource,kotlin.Function0)`. To add a background to the `https://developer.android.com/reference/kotlin/androidx/compose/material/ListItem.composable#ListItem(androidx.compose.ui.Modifier,kotlin.Function0,kotlin.Function0,kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Function0)`, wrap it with a `https://developer.android.com/reference/kotlin/androidx/compose/material/Surface.composable#Surface(androidx.compose.ui.Modifier,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.foundation.BorderStroke,androidx.compose.ui.unit.Dp,kotlin.Function0)`.

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

- one-line items

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

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

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

```kotlin
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: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | Modifier to be applied to the list item |
| `icon: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | The leading supporting visual of the list item |
| `secondaryText: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | The secondary text of the list item |
| `singleLineSecondaryText: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | Whether the secondary text is single line |
| `overlineText: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | The text displayed above the primary text |
| `trailing: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | The trailing meta text, icon, switch or checkbox |
| `text: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The primary text of the list item |