Scrollable Lists and Grids: The Affirmations App

Open almost any app on your phone: WhatsApp chats, a bank's transaction history, a shop's product catalogue, your music library. Every one of them is built around a scrolling list (or a grid) of items. If you can build lists well, you can build the core of most apps.

In this lesson you will build Affirmations, an app that shows a scrollable list of cards, each with a picture and an encouraging sentence. Then you will turn the list into a grid, and finish by giving your app its own launcher icon.

This lesson covers four items from Unit 3 of Google's official Android Basics with Compose course: Intro to Affirmations app, Add a scrollable list, Change the app icon and Practice: Build a grid.

By the end you will be able to:

• Model list data with a Kotlin data class.
• Store text in strings.xml and images in res/drawable, and reference them with @StringRes and @DrawableRes.
• Build a card with Card, Image and Text.
• Display a long list efficiently with LazyColumn and items.
• Display a grid with LazyVerticalGrid and GridCells.
• Create an adaptive launcher icon with Image Asset Studio.

Big idea: a list on screen is just a list in your code, turned into UI one item at a time. Data first, then a function that draws one item, then a lazy container that repeats it.

• Data classes (lesson 11). data class gives you a tidy way to bundle values together and automatically adds toString, equals and copy.
• Lists (lesson 14). listOf(...) creates a read-only list, and you loop over it.
• Row, Column and Modifier (lesson 16). Lists are built from the same layout pieces.
• Resources. Android keeps text, images, colours and sizes in the res folder, separate from code. This makes translation and theming easy. You will use res/values/strings.xml and res/drawable today.

You could draw a list of 1,000 items by putting 1,000 Texts inside a Column. It would work for ten items and then your app would freeze, because the Column creates every child immediately, even the 990 that are far off screen.

A lazy container is smarter. It only composes the items you can actually see (plus a few just outside the screen), and it throws away or reuses the rest as you scroll. Think of a waiter at a huge buffet who only brings the dishes you are looking at, instead of piling every dish on your table at once.

Inside a lazy container you do not write a loop. You describe the items with a small DSL (a mini-language built from lambdas), and the container decides when to run your code:

LazyColumn {
 items(myList) { item ->
 Text(item)
 }
}

The lambda after items(myList) is run once per visible item, and item is the element for that row.

Create a new Empty Activity project called Affirmations (package com.example.affirmations).

The model

Right-click the package, choose New > Kotlin Class/File, name it Affirmation, and write a data class:

package com.example.affirmations.model
import androidx.annotation.DrawableRes
import androidx.annotation.StringRes
data class Affirmation(
 @StringRes val stringResourceId: Int,
 @DrawableRes val imageResourceId: Int
)

Notice that it stores numbers, not text and pictures. Android generates a unique integer ID for every resource in the class R. R.string.affirmation1 is an Int. The annotations @StringRes and @DrawableRes are safety labels: Android Studio now warns you if you accidentally pass a drawable ID where a string ID is expected, even though both are just Ints.

(You will need a folder named model under the package. Create it with New > Package, or just keep the file in the main package and adjust the package line.)

The text resources

Open app/src/main/res/values/strings.xml and add ten sentences. Here are the first few:

<resources>
 <string name="app_name">Affirmations</string>
 <string name="affirmation1">I am strong.</string>
 <string name="affirmation2">I believe in myself.</string>
 <string name="affirmation3">Each day is a new opportunity to grow.</string>
 <string name="affirmation4">I can learn anything I set my mind to.</string>
 <string name="affirmation5">Small steps still move me forward.</string>
 <string name="affirmation6">I am proud of how far I have come.</string>
 <string name="affirmation7">I choose to see the good in today.</string>
 <string name="affirmation8">Mistakes are proof that I am trying.</string>
 <string name="affirmation9">I am becoming a better developer every day.</string>
 <string name="affirmation10">Today I will build something worth sharing.</string>
</resources>

Putting text in strings.xml instead of inside code means you can later translate the app (for example into Yoruba or Hausa) by adding a values-yo or values-ha folder, without touching a single line of Kotlin.

The image resources

You need ten pictures in res/drawable. Pick the route that suits you:

1. Your own photos or images. Copy ten small JPG or PNG files into res/drawable. File names must use only lowercase letters, digits and underscores, for example image1.jpg. Keep them small (under 300 KB each) so the app stays light.
2. No images? Use free built-in icons. Choose File > New > Vector Asset (or right-click res/drawable, then New > Vector Asset), click the clip-art button, pick an icon, name it image1, and finish. Repeat for ten icons. These are scalable and tiny.

Whichever you choose, name the ten resources image1 to image10.

The data source

Create Datasource.kt that builds the list:

package com.example.affirmations.data
import com.example.affirmations.R
import com.example.affirmations.model.Affirmation
class Datasource {
 fun loadAffirmations(): List<Affirmation> {
 return listOf(
 Affirmation(R.string.affirmation1, R.drawable.image1),
 Affirmation(R.string.affirmation2, R.drawable.image2),
 Affirmation(R.string.affirmation3, R.drawable.image3),
 Affirmation(R.string.affirmation4, R.drawable.image4),
 Affirmation(R.string.affirmation5, R.drawable.image5),
 Affirmation(R.string.affirmation6, R.drawable.image6),
 Affirmation(R.string.affirmation7, R.drawable.image7),
 Affirmation(R.string.affirmation8, R.drawable.image8),
 Affirmation(R.string.affirmation9, R.drawable.image9),
 Affirmation(R.string.affirmation10, R.drawable.image10)
 )
 }
}

Why a class with a function instead of a bare list? Later in this course (lessons 30 and 34) the data will come from a repository, a web service or a database, and a function is the natural seam where that change happens.

Always build one item first and preview it before you worry about the list. Open MainActivity.kt and add this composable. Add the imports as Android Studio suggests (Alt + Enter), or copy this block:

import androidx.compose.foundation.Image
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Card
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.res.painterResource
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.tooling.preview.Preview
import androidx.compose.ui.unit.dp
import com.example.affirmations.R
import com.example.affirmations.model.Affirmation
@Composable
fun AffirmationCard(affirmation: Affirmation, modifier: Modifier = Modifier) {
 Card(modifier = modifier) {
 Column {
 Image(
 painter = painterResource(affirmation.imageResourceId),
 contentDescription = stringResource(affirmation.stringResourceId),
 modifier = Modifier
 .fillMaxWidth()
 .height(194.dp),
 contentScale = ContentScale.Crop
 )
 Text(
 text = stringResource(affirmation.stringResourceId),
 modifier = Modifier.padding(16.dp),
 style = MaterialTheme.typography.headlineSmall
 )
 }
 }
}
@Preview(showBackground = true)
@Composable
fun AffirmationCardPreview() {
 AffirmationCard(Affirmation(R.string.affirmation1, R.drawable.image1))
}

What to notice:

• Card is a Material 3 container with rounded corners and elevation.
• stringResource(id) turns the Int ID into the actual text, and it respects the user's language.
• painterResource(id) loads the drawable.
• contentDescription is read aloud by screen readers, so we reuse the sentence. (A purely decorative picture can use null; lesson 47 explains when.)
• ContentScale.Crop fills the box and crops the extra, so differently-shaped pictures look uniform.
• MaterialTheme.typography.headlineSmall takes its size and weight from the theme, so you can restyle the whole app later in one place (lesson 22).

Open the Preview pane. You should see one card: a picture on top, the sentence beneath.

Now repeat that card for every affirmation.

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import com.example.affirmations.data.Datasource
@Composable
fun AffirmationList(
 affirmationList: List<Affirmation>,
 modifier: Modifier = Modifier
) {
 LazyColumn(
 modifier = modifier,
 contentPadding = PaddingValues(8.dp),
 verticalArrangement = Arrangement.spacedBy(8.dp)
 ) {
 items(affirmationList, key = { it.stringResourceId }) { affirmation ->
 AffirmationCard(affirmation = affirmation)
 }
 }
}
@Composable
fun AffirmationsApp(modifier: Modifier = Modifier) {
 AffirmationList(
 affirmationList = Datasource().loadAffirmations(),
 modifier = modifier
 )
}

Then call it from setContent. The Empty Activity template wraps content in a Scaffold so that your content does not hide behind the system bars. Use the padding it gives you:

setContent {
 AffirmationsTheme {
 Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
 AffirmationsApp(modifier = Modifier.padding(innerPadding))
 }
 }
}

(Scaffold needs import androidx.compose.material3.Scaffold and fillMaxSize needs import androidx.compose.foundation.layout.fillMaxSize.)

Understanding each piece

• contentPadding adds space inside the scrolling area, so the first card is not glued to the top and the last card can scroll clear of the bottom edge.
• Arrangement.spacedBy(8.dp) puts an 8 dp gap between neighbouring items, so you never need margins on each card.
• items(list) { ... } runs the lambda for each visible element.
• key = { it.stringResourceId } gives each item a stable identity. When a list changes (an item is added, removed or moved), keys let Compose track which item is which instead of rebuilding everything. Keys must be unique and stable, and the string resource ID is both. Lesson 39 covers keys in depth.

Run the app and scroll. Ten cards, smooth scrolling.

Experiment: change ten to ten thousand. Make a loop that repeats loadAffirmations() a thousand times (without keys, because duplicates would clash). The app stays smooth, because only a handful of items exist at any moment. That is the entire point of a lazy list.

A grid lays items out in columns. The container takes a columns rule that says how many:

import androidx.compose.foundation.lazy.grid.GridCells
import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
import androidx.compose.foundation.lazy.grid.items
@Composable
fun AffirmationGrid(
 affirmationList: List<Affirmation>,
 modifier: Modifier = Modifier
) {
 LazyVerticalGrid(
 columns = GridCells.Adaptive(minSize = 160.dp),
 modifier = modifier,
 contentPadding = PaddingValues(8.dp),
 horizontalArrangement = Arrangement.spacedBy(8.dp),
 verticalArrangement = Arrangement.spacedBy(8.dp)
 ) {
 items(affirmationList) { affirmation ->
 AffirmationCard(affirmation = affirmation)
 }
 }
}

There are two ways to say how many columns:

Adaptive is usually the better choice, because it quietly adjusts when the user rotates the phone or opens your app on a large screen. Note that items for the grid comes from a different import (androidx.compose.foundation.lazy.grid.items) than the items for LazyColumn. Importing the wrong one is the most common error with grids.

The default icon is the green Android robot. Every real app needs its own.

Using Image Asset Studio

1. In the Android view, right-click the res folder.
2. Choose New > Image Asset.
3. For Icon Type choose Launcher Icons (Adaptive and Legacy).
4. On the Foreground Layer tab choose a source: Image (your own logo), Clip Art (a built-in icon) or Text. Use Resize to keep the artwork inside the safe zone, the central circle.
5. On the Background Layer tab pick a colour or image.
6. Check the preview in different shapes (circle, square, squircle), then click Next and Finish.

What "adaptive" means

Since Android 8, an icon is made of two layers, a foreground and a background. Each phone maker applies its own mask (circle, rounded square, and so on) and the system can move the layers slightly for parallax effects. If you put important artwork near the edges it gets cropped. Keeping it inside the safe zone makes the icon look right on every phone.

Newer Android versions also support a themed icon that takes on the user's wallpaper colours. For that, provide a single-colour monochrome layer. Image Asset Studio can generate one from your foreground.

Finally, check AndroidManifest.xml. The <application> tag points at your icon through android:icon="@mipmap/ic_launcher" and android:roundIcon="@mipmap/ic_launcher_round". Run the app and look at the launcher: your icon replaces the robot.

Mistake #1: A Column for a long list. What happens: every item is composed immediately, memory climbs, scrolling stutters or the list does not scroll at all unless you add verticalScroll. The fix: LazyColumn.

Mistake #2: Nested vertical scrolling. The wrong code: putting a LazyColumn inside a Column that has verticalScroll, or inside another vertical LazyColumn. What happens: a crash saying vertically scrollable components were measured with an infinite maximum height. The fix: one scrolling container per direction. Put extra items inside the same LazyColumn as separate item { } entries.

Mistake #3: Wrong items import. Symptom: red underline on items inside a grid. The fix: for LazyVerticalGrid, import androidx.compose.foundation.lazy.grid.items; for LazyColumn, androidx.compose.foundation.lazy.items.

Mistake #4: Duplicate or changing keys. What happens: a crash complaining that the key was already used. The fix: keys must be unique and stable. Never use the item's position in the list as the key if the list can change order.

Mistake #5: Wrong resource folder or file names. Symptom: R.drawable.Image1 does not exist. The fix: resource names are lowercase letters, digits and underscores only. Image1.jpg is rejected, image1.jpg works.

Mistake #6: Huge images. What happens: the app is slow and uses a lot of memory because full-size camera photos are decoded. The fix: resize images before adding them, or use vector assets. Lesson 31 shows how to load remote images efficiently.

Mistake #7: Missing contentDescription thinking. The fix: give meaningful pictures a description and pass null only for decorative ones.

Mistake #8: Hard-coded text. What happens: Android Studio warns Hardcoded string. The fix: put text in strings.xml and read it with stringResource.

Question 1. Why is LazyColumn better than Column for a long list?

Question 2. What is the purpose of @StringRes and @DrawableRes?

Question 3. What is the difference between GridCells.Fixed(2) and GridCells.Adaptive(160.dp)?

Question 4. Why give items a key?

Question 5. What are the two layers of an adaptive icon, and why keep artwork in the safe zone?

Go deeper: official resources

• Android Basics with Compose, Unit 3, Pathway 2: Build a scrollable list: the official pathway for this lesson, including the Affirmations app and the grid practice.
• Android Basics with Compose course page: all eight units.
• Jetpack Compose for Android developers, pathway 2: Layouts, theming and animation: lazy layouts are covered in more depth, which you will meet in lesson 39.