Discovering Material 3 for Android — ListItem

6 min readApr 20, 2023

This series of articles is designed to help you explore the latest addition to Material 3 for Android. In this series, we will take a closer look at the different components and features of Material 3, and explore how they can be used to create modern and user-friendly Android apps.

Android Makers by droidcon 2023 schedule app

It’s about Lists

Displaying a set of data that a user needs to interact with is an essential part of mobile app development. As mobile engineers, our goal is to allow users to view large amounts of data in a structured and organized manner. The visual impact of the app is often the preferred choice but we also have to deal with business constraints and grant our users the best experience possible.

List vs Cards

Let’s talk about design briefly if you don’t mind.

In Android, both lists and cards are commonly used to display data to users. However, there are some key differences between the two that can affect how data is presented and how users interact with it. I think, we should always ask ourself some questions before choosing between them:

how useful is it to our users to display this set of data?
how do we want our users to interact with them?

Lists

Each item in the list is displayed as a separate entity, with its own set of attributes such as text, icons, and images.

Lists tend to have a more hierarchical structure, with each item in the list occupying its own space and having equal visual weight.

Cards

Cards are used to display a more focused and condensed view of data. A card typically includes a single piece of information or a small collection of related information, presented in a container with rounded corners and a drop shadow to create a sense of depth.

Cards tend to be more visually dominant, with the focus on the card’s content rather than the surrounding elements.

Differences

One key difference between lists and cards is their visual hierarchy. Lists are often used to display data that users can interact with, such as selecting an item or scrolling through a list.

Lists are best used for displaying collections of items that users can interact with, while cards are best used for presenting focused, condensed views of information.

Dealing with Lists in Android

Historically, lists are typically displayed using RecyclerView. However, they can sometimes be complicated to work with and customize (+ the boilerplate!!), which is why Jetpack Compose LazyColumn (and LazyRow) components are a great new additions to Android app development.

Here’s an example of how to create a simple list using LazyColumn in Jetpack Compose:

LazyColumn {
    items(listOf("Item 1", "Item 2", "Item 3")) { item ->
        Text(text = item)
    }
}

Experimental ListItem component

As of today, official specs do not match the material3 component, so here is how I understand the component

The Material 3 ListItem component is made up of several parts, including:

ListItem itself: it can be customized with ListItemColors, tonalElevation and shadowElevation.
Headline: This is the main text that is displayed on the list item. It can be customized with different text styles and colors.
Supporting: This is the smaller text that is displayed below the Headline. It can be used to display additional information about the list item.
Overline: Usually for text in uppercase, it is displayed above the Headline. If not null, Trailing and Leading will be horizontally aligned.
Leading: use for icons or images
Trailing: use for actions

@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

Using Material 3 ListItem

Using Material 3 ListItem is incredibly easy and intuitive. To get started, you will need to add the Material 3 dependency to your project, and then simply add a ListItem component.

Allow me to share some examples from the official source code:

@Preview
@Composable
fun OneLineListItem() {
  ListItem(
      headlineContent = { Text("One line list item with 24x24 icon") },
      leadingContent = {
        Icon(
            Icons.Filled.Favorite,
            contentDescription = "Localized description",
        )
      }
  )
}

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

@Preview
@Composable
fun ThreeLineListItem() {
  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") }
  )
}

⚠️ Notice how the leading and the trailing sections behave when we specify an overline section

Benefits of Material 3 ListItem

One of the main benefits of using Material 3 ListItem is that it is incredibly easy to use and customize. This makes it an ideal component for developers who want to create beautiful and functional lists without spending too much time on customization.

Another benefit of using Material 3 ListItem is that it is part of the Material Design system, which means that it is already designed to be intuitive and user-friendly. This can help to improve the overall user experience of your app and make it more appealing to users.

Imagine you want more? Like a Card? With Jetpack Compose, you could just wrap your ListItem into a Card component.

⚠️ I used a Box here just for the screenshot below 🙂

@Preview
@Composable
fun ThreeLineListItem() {
  Box(modifier = Modifier
      .background(MaterialTheme.colorScheme.background)
      .padding(16.dp)) {
    Card {
      ListItem(
          colors = ListItemDefaults.colors(
              containerColor = MaterialTheme.colorScheme.surfaceVariant,
          ),
          headlineContent = { Text("Three line list item") },
          overlineContent = { Text("OVERLINE") },
          supportingContent = { Text("Secondary text") },
          leadingContent = {
            Icon(
                Icons.Filled.Favorite,
                contentDescription = "Localized description",
            )
          },
          trailingContent = { Text("meta") }
      )
    }
  }
}

More colors ? Then let us override the default

colors = ListItemDefaults.colors(
    containerColor = MaterialTheme.colorScheme.primaryContainer,
    headlineColor = MaterialTheme.colorScheme.onPrimaryContainer,
    leadingIconColor = MaterialTheme.colorScheme.onPrimaryContainer,
    overlineColor = MaterialTheme.colorScheme.onPrimaryContainer,
    supportingColor = MaterialTheme.colorScheme.onPrimaryContainer,
    trailingIconColor = MaterialTheme.colorScheme.onPrimaryContainer,
),

Wait, is it only for items?

Material 3 ListItem is an excellent addition to Android app development, as it provides a simple and streamlined way to create lists in addition to LazyColumn or LazyRow.

This new component is easy to use and customize and if we think out of the box for a minute, we can totally use it as a “scaffold” or kind of a layout dedicated to other components: it does not have to be exclusively used for list item!