Previously: Parts 1 to 4 made screens readable, operable, testable, and alive for assistive technology. This final part is about a different kind of inclusion: the hundreds of millions of people who read Arabic, Hebrew, Persian, or Urdu, right to left.

TL;DR Compose mirrors most layouts for free, as long as you say start and end, never left and right*.*** The rest of RTL support is judgement. Directional icons must flip; play buttons, checkmarks, and clocks must not. Phone numbers and English product names inside Arabic sentences need isolating. Raw gesture math, slide animations, and custom Canvas drawing don't mirror on their own. Test all of it in minutes with a forced-RTL preview and the ar-XB pseudolocale, then lock the result in with a layout assertion and reviewed LTR/RTL screenshot baselines.

The back arrow that points the wrong way

An Arabic launch goes out. The layouts mirror nicely: titles sit on the right, lists align to the right, and the navigation icon moves to the top-right corner. Then a reviewer posts a screenshot. The back arrow, now on the right edge, still points left, deeper into the screen, which in an RTL layout means forward.

The cause is one line from years ago:

// ❌ A fixed, left-pointing arrow. It moves with the layout but never turns around.
Icon(Icons.Filled.ArrowBack, contentDescription = stringResource(R.string.cd_navigate_up))

It’s a small bug that tells every RTL user the app was never designed with them in mind. It also confuses screen reader users: TalkBack says “Navigate up” about an arrow that visually points forward. The fix is one word:

// ✅ Flips automatically in RTL layouts
Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = stringResource(R.string.cd_navigate_up))

The AutoMirrored icon set has existed since material-icons 1.6, and the old directional icons are deprecated in favour of it. If your build shows deprecation warnings for Icons.Filled.ArrowBack, that's your RTL backlog announcing itself.

How Compose handles layout direction

Layout direction is part of the composition, exposed as LocalLayoutDirection. Compose derives it from the device configuration: an Arabic or Hebrew locale means LayoutDirection.Rtl. Every direction-aware API reads it, so start resolves to the left edge in English and to the right edge in Arabic, with no code on your part.

There’s one switch upstream of all of this. Your manifest must opt in:

<application
    android:supportsRtl="true"
    ... >

Without it, the configuration reports left-to-right for every locale, and nothing in this post applies. New projects set it by default. Older apps, and some white-label templates, quietly don’t.

The rule that follows is simple: use the start/end API, and treat every left/right API as a decision you need to justify.

@Composable
fun IngredientRow(ingredient: Ingredient, onRemove: () -> Unit, modifier: Modifier = Modifier) {
    Row(
        modifier = modifier
            .fillMaxWidth()
            .padding(start = 16.dp, end = 8.dp),       // ✅ not absolutePadding(left = 16.dp)
        horizontalArrangement = Arrangement.spacedBy(12.dp, Alignment.Start),
        verticalAlignment = Alignment.CenterVertically,
    ) {
        Text(
            text = ingredient.quantityLabel,
            textAlign = TextAlign.End,                   // ✅ not TextAlign.Right
            modifier = Modifier.width(56.dp),
        )
        Text(ingredient.name, modifier = Modifier.weight(1f))
        IconButton(onClick = onRemove) {
            Icon(Icons.Outlined.Close, contentDescription = stringResource(R.string.cd_remove_ingredient, ingredient.name))
        }
    }
}

Two details catch even experienced teams:

• Modifier.offset(x = …) mirrors. Its documentation states that a positive x moves content right in LTR and left in RTL, toward the end. That's usually what you want, for example nudging a badge toward the edge of an icon. When an offset is genuinely physical, such as aligning with a fixed piece of artwork, use absoluteOffset and leave a comment explaining why.
• Reading order follows direction too. Part 1 explained that TalkBack orders siblings top to bottom, then start to end. Use start/end APIs and TalkBack reads Arabic screens right to left automatically. Hard-code absolute positions and you break visual order and reading order in one go.

Icons: flip the ones that point

An icon should mirror when it shows direction through the reading flow: back, forward, next, previous, send, list indentation, or a chevron that opens something “after” the current item. An icon should not mirror when its direction comes from the physical world or a universal convention.

1. Mirror: back and forward arrows, chevrons for navigation, send, undo and redo, “next step” indicators, text-indent icons.
2. Don’t mirror:

• Media playback controls. Play, fast-forward, and rewind describe the direction of the media’s timeline, not of reading.
• Checkmarks. A checkmark is a universal symbol, not a direction.
• Clocks and timers. Clock hands turn the same way in every country.
• Logos, and any icon containing Latin letters or numbers.

For your own vector drawables, the flag lives in the XML:

<!-- res/drawable/ic_reply.xml -->
<vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:autoMirrored="true"
    android:width="24dp" android:height="24dp"
    android:viewportWidth="24" android:viewportHeight="24">
    <!-- paths -->
</vector>

The common failure is the reverse of the opening bug. A well-meaning bulk change adds autoMirrored="true" to every drawable, and suddenly the play button in your Arabic build points backwards. Review mirroring per icon, not per folder.

Edge cases: where direction hides

Mixed-direction text

Arabic sentences regularly contain English: product names, usernames, brand names. Unicode’s bidirectional algorithm usually places them correctly. It goes wrong at the edges, when an inserted LTR fragment starts or ends with numbers or punctuation. Then the surrounding RTL text can grab those characters and reorder them. The fix is to isolate the inserted value so it’s laid out as one unit:

import androidx.compose.ui.platform.LocalConfiguration
import androidx.core.os.ConfigurationCompat
import androidx.core.text.BidiFormatter
import java.util.Locale

@Composable
fun rememberBidiFormatter(): BidiFormatter {
    val locale = ConfigurationCompat.getLocales(LocalConfiguration.current)[0] ?: Locale.getDefault()
    return remember(locale) { BidiFormatter.getInstance(locale) }
}

@Composable
fun OrderConfirmation(productName: String) {
    val bidi = rememberBidiFormatter()
    // Without unicodeWrap, a name like "Pixel 9 Pro" can have its trailing
    // number pulled into the Arabic text around it.
    Text(stringResource(R.string.order_confirmed, bidi.unicodeWrap(productName)))
}

Wrap every runtime value you insert into a translated string: names, titles, search queries. The cost is negligible, and it removes an entire class of bug reports that are almost impossible to reproduce if you don’t read the language.

Numbers, phone numbers, and charts

Digits always read left to right, even inside RTL text. What breaks is sequences with separators. A phone number like +91 98765 43210, placed in an RTL paragraph, can be displayed with its groups in reverse order. To a reader it's a different number entirely. The same applies to ranges ("10–20"), IBANs, card numbers, and version strings.

Force these values to left-to-right explicitly:

// Display: isolate as LTR inside any surrounding text
Text(bidi.unicodeWrap(phoneNumber, TextDirectionHeuristicsCompat.LTR))

// Input: keep the field's text LTR while the field itself stays in the RTL layout
OutlinedTextField(
    value = phone,
    onValueChange = onPhoneChange,
    label = { Text(stringResource(R.string.label_phone)) },
    textStyle = LocalTextStyle.current.copy(textDirection = TextDirection.Ltr),
    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Phone),
)

Two more number traps:

• Locale digits. Formatting a number with the user’s locale may produce Eastern Arabic digits (٠١٢٣…), depending on the locale. That’s correct for display. Never parse displayed text back into numbers, and never build IDs or API parameters from locale-formatted strings.
• Charts. Should a time axis run right to left? There is no universal answer. Many bidirectional design guidelines flip timelines so “later” sits toward the reading end, while many finance apps keep charts LTR because that’s what their users see everywhere else. Decide deliberately, apply it consistently, and ask people who read the language every day.

Gestures, animations, and custom drawing

This is where layouts that mirror perfectly still feel wrong. Anything built on direction-aware APIs is handled for you. Anything built on raw coordinates is not.

Handled for you: HorizontalPager, LazyRow, horizontalScroll, SwipeToDismissBox (its values are StartToEnd and EndToStart), and AnimatedContent transitions built with SlideDirection.Start and SlideDirection.End.

You must flip yourself:

// 1. Slide animations with raw pixel offsets
AnimatedContent(
    targetState = step,
    transitionSpec = {
        // ❌ slideInHorizontally { it } always enters from the physical right.
        // ✅ Start/End resolve against the current layout direction.
        val direction = if (targetState > initialState) {
            AnimatedContentTransitionScope.SlideDirection.Start
        } else {
            AnimatedContentTransitionScope.SlideDirection.End
        }
        slideIntoContainer(direction) togetherWith slideOutOfContainer(direction)
    },
    label = "wizard-step",
) { current -> WizardStep(current) }

// 2. Raw drag gestures: dragAmount is in screen coordinates, not reading direction
@Composable
fun Modifier.swipeBetweenPhotos(onNext: () -> Unit, onPrevious: () -> Unit): Modifier {
    val isRtl = LocalLayoutDirection.current == LayoutDirection.Rtl
    val currentOnNext by rememberUpdatedState(onNext)
    val currentOnPrevious by rememberUpdatedState(onPrevious)

    return pointerInput(isRtl) {
        val threshold = 56.dp.toPx()
        var total = 0f
        detectHorizontalDragGestures(
            onDragStart = { total = 0f },
            onDragEnd = {
                // Normalise so that positive always means "toward the end".
                val towardEnd = if (isRtl) -total else total
                when {
                    towardEnd < -threshold -> currentOnNext()      // swiped toward start: next
                    towardEnd > threshold -> currentOnPrevious()
                }
            },
        ) { _, dragAmount -> total += dragAmount }
    }
}

The rememberUpdatedState calls are there for a reason too. pointerInput is keyed only on direction, so without them the gesture would keep calling whichever lambdas existed on first composition. And per Part 2: any swipe-only interaction also needs a custom accessibility action, such as "Next photo," because swipes aren't available to everyone.

// 3. Custom Canvas drawing: coordinates are physical
@Composable
fun ReadingProgressBar(progress: Float, modifier: Modifier = Modifier) {
    val track = MaterialTheme.colorScheme.surfaceVariant
    val fill = MaterialTheme.colorScheme.primary
    Canvas(modifier.fillMaxWidth().height(6.dp)) {
        val mirror = layoutDirection == LayoutDirection.Rtl   // DrawScope knows the direction
        scale(scaleX = if (mirror) -1f else 1f, scaleY = 1f) { // mirror the shapes, not the text
            drawRect(track)
            drawRect(fill, size = Size(size.width * progress.coerceIn(0f, 1f), size.height))
        }
    }
}

Mirror shapes this way, never text. A drawText call inside a mirrored scale block renders backwards, letters and all. Draw labels outside the mirrored block, at positions you calculate from layoutDirection.

Testing RTL in minutes, not sprints

You don’t need to read Arabic to catch 90% of RTL bugs. You need five habits, from fastest to most thorough:

1. Previews in both directions. One extra annotation per component:

@Preview(name = "LTR · English", locale = "en")
@Preview(name = "RTL · Arabic", locale = "ar")
@Composable
private fun IngredientRowPreview() {
    AppTheme { IngredientRow(ingredient = sampleIngredient, onRemove = {}) }
}

For a reusable wrapper that works in tests and screenshot tooling too:

@Composable
fun ForceRtl(content: @Composable () -> Unit) {
    CompositionLocalProvider(LocalLayoutDirection provides LayoutDirection.Rtl, content = content)
}

2. Pseudolocales. Enable them for debug builds:

android {
    buildTypes.getByName("debug") {
        isPseudoLocalesEnabled = true
    }
}

Then make AR (XB) the active language in your device’s language settings. It renders your English strings right to left, with the characters reversed, so you can review RTL layouts without any translations. Its sibling, en-XA, adds accents and expands text length to expose clipping, and it flags hard-coded strings that never went through resources.

3. Force RTL on a device. In Developer options, enable Force RTL layout direction. It mirrors every app without changing the language, which makes it handy for checking third-party SDK screens your previews never see.

4. A layout assertion in CI. Part 3’s tooling extends naturally:

@Test
fun topBar_backButtonSitsAtStartInRtl() {
    rule.setContent { ForceRtl { AppTheme { RecipeTopBar(title = "Carbonara", onBack = {}) } } }

    val root = rule.onRoot().getBoundsInRoot()
    val back = rule.onNodeWithTag(TestTags.BACK).getBoundsInRoot()

    assertTrue(back.left > root.width / 2, "Back button should sit on the right edge in RTL")
}

This test proves placement, not orientation. The opening bug would pass it: the icon reaches the right edge while the arrow keeps pointing left. Bounds can’t see the pixels inside an icon, so pair this with the next habit.

5. Reviewed LTR/RTL screenshot baselines. Keep one small fixture holding an icon that must mirror and one that must not, and record it in both directions.

@Composable
fun DirectionalIconFixture() {
    Row(
        horizontalArrangement = Arrangement.spacedBy(16.dp),
        verticalAlignment = Alignment.CenterVertically,
    ) {
        // Must mirror
        Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = null)
        // Must NOT mirror
        Icon(Icons.Filled.PlayArrow, contentDescription = null)
    }
}

@Preview(name = "LTR", locale = "en")
@Preview(name = "RTL", locale = "ar")
@Composable
private fun DirectionalIconFixturePreview() {
    AppTheme { DirectionalIconFixture() }
}

Note: Paparazzi and Roborazzi don’t read the @Preview annotations, so with those tools set the locale or layout direction in the test configuration. Compose Preview Screenshot Testing does use them.

Expected result: the arrow points left in LTR and right in RTL, while the play triangle points right in both. A missing flip shows up as a wrong arrow, and an overbroad mirroring change (the bulk autoMirrored="true" mistake) shows up as a backwards play button. Because both icons sit in one fixture, anyone updating a shared component can see the intended difference at a glance. Record with Paparazzi, Roborazzi, or Compose Preview Screenshot Testing, whichever you already use.

Baselines only help if diffs are reviewed. Check the first recording by eye, ideally with someone who reads an RTL language, and treat “update snapshots” commits with suspicion.

A screen-by-screen audit in RTL takes about two minutes per screen. Check each of these:

• Alignment and padding mirror.
• Directional icons flip; media icons, checkmarks, and logos don’t.
• The screenshot fixture still shows the arrow flipped and the play button unchanged.
• Inserted names and numbers read correctly.
• Swipes and slide animations move with the reading direction.
• Custom drawing such as progress bars and charts fills from the start.
• TalkBack reads right to left.

Common mistakes

• Hard-coded left/right in custom drawing. Canvas code, drawBehind, and custom Layout placement all use physical coordinates. Read layoutDirection explicitly or mirror with scale, and keep text out of the mirrored block.
• Mirroring icons that shouldn’t mirror. A bulk autoMirrored="true" across the drawable folder flips play buttons, checkmarks, and logos. Decide per icon.
• Forgetting supportsRtl. A single missing manifest attribute silently disables every direction-aware API in the app.
• Concatenating strings around user content. Build sentences from resources with placeholders, and wrap the inserted values. Concatenation can’t be reordered by translators and can’t be isolated.
• Trusting bounds tests for icon direction. A layout assertion confirms where an icon sits, not which way it points. Add a reviewed LTR/RTL screenshot baseline for directional and non-directional icons.

Series wrap-up: an app that works for far more people

Five parts, one idea: the pixels are only one of the interfaces you ship. The semantics tree, the reading order, the announcements, and the layout direction are interfaces too, and they’re used by real people every day.

• Part 1, Raising the Floor, set the baseline: meaningful labels, 48dp touch targets, readable contrast, meaning that survives without color, and intentional reading order.
• Part 2, From Five Stars to One Sentence, turned a custom rating widget into one operable node with a state, a range, and custom actions.
• Part 3, Green Builds, Blind Spots, made all of it testable in five layers, from semantics assertions to a ten-minute TalkBack routine.
• Part 4, When the Screen Changes Silently, covered live regions, headings, and focus for screens that change after they load.
• Part 5, this post, made every screen direction-aware.

Here is everything condensed into one release checklist. Print it, or paste it into your pull request template.

What to do next week

1. Add one layer of tests. Pick your most valuable flow and add Part 3’s targeted and bulk assertions to CI. It’s an afternoon’s work that protects everything else.
2. Run both manual passes on that flow: the ten-minute TalkBack routine, then two minutes per screen in ar-XB. Write down everything you find. That list is your roadmap.
3. Add the icon fixture from Part 5 to your screenshot suite while you’re there. It takes minutes and guards your shared components.
4. Fix it in the design system, not the screen. Required contentDescription parameters, a SectionHeader with heading(), auto-mirrored icons by default. Every fix in a shared component pays out on every screen.
5. Talk to users. Five sessions with people who use TalkBack, Switch Access, magnification, or an RTL language every day will reprioritise your backlog better than any checklist, this one included.

Further reading

• Accessibility in Jetpack Compose: the official guide to semantics, traversal, merging, and testing.
• Make apps more accessible: platform-level Android guidance.
• Test your app with pseudolocales: setup for en-XA and ar-XB.
• Web Content Accessibility Guidelines (WCAG) 2.2: the standard behind contrast ratios and target sizes.
• Accessibility Test Framework for Android: the engine behind ATF checks and Accessibility Scanner.
• Material Design: Bidirectionality: visual guidance on mirroring layouts and icons.

Thanks for reading the series. If one screen in your app works for one more person next month than it did last month, it did its job.

📱 Level Up Your Android System Design Game

If you’re prepping for a senior Android role and system design rounds are the part that makes you sweat, I highly recommend “Mastering Android System Design” — a 37-chapter playbook that treats Android like the constrained runtime it actually is, not a small server. It covers Binder IPC, ART’s GC, process death, and background execution limits, then walks through the CRDDS interview framework and 13 full worked case studies (chat, ride-hailing, video streaming, payments, and more) carried end-to-end through API design, offline sync, and the Android-specific edge cases that trip candidates up mid-interview.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover.

Originally published on Medium.

Previously: Parts 1 to 3 made static screens accessible and kept them that way with tests. This part is about everything that happens after the screen first appears.

TL;DR Sighted users notice change for free: a badge ticks up, an error turns red, results slide in. TalkBack users only notice what is spoken or what receives focus*. Three tools close that gap:*

• Live regions announce changes without moving focus.
• Headings let people jump between sections instead of swiping through everything.
• Deliberate focus management puts the user where the next action is, but only at moments they’ll expect.

Each one is easy to add and just as easy to overdo, so this post spends as much time on restraint as on code.

The silent cart counter

A user is on a product page with TalkBack running. They double-tap Add to cart. On screen, the badge on the cart icon in the top bar ticks from 3 to 4. That’s the confirmation.

TalkBack says nothing. Its focus is still on the button, and the change happened somewhere else. The user doesn’t know whether the tap worked, so they tap again. Now there are five items in the cart, and they only wanted one more.

No crash, no visual bug, and the code from Part 1 passes every check in Part 3. The screen changed, and only some users were told.

Live regions: announce without moving

A live region is a node that asks accessibility services to announce it whenever its content changes, wherever focus happens to be. In Compose it’s one semantics property:

@Composable
fun CartAction(itemCount: Int, onOpenCart: () -> Unit) {
    val description = if (itemCount == 0) {
        stringResource(R.string.cd_cart_empty)
    } else {
        pluralStringResource(R.plurals.cd_cart_items, itemCount, itemCount)
    }

    IconButton(
        onClick = onOpenCart,
        modifier = Modifier.semantics {
            contentDescription = description
            liveRegion = LiveRegionMode.Polite
        },
    ) {
        BadgedBox(
            badge = {
                if (itemCount > 0) {
                    Badge(Modifier.clearAndSetSemantics { }) { Text(itemCount.toString()) }
                }
            },
        ) {
            Icon(Icons.Outlined.ShoppingCart, contentDescription = null)
        }
    }
}

This is Part 1’s cart button with one structural change: the description moved from the Icon up to the IconButton, onto the same node as the live region. That's deliberate. Keep the live region on the node that owns the changing text, rather than relying on changes inside merged children to bubble up to a live parent. It's the most predictable arrangement across Compose and TalkBack versions. Now adding an item produces "Shopping cart, 4 items" after TalkBack finishes whatever it was saying.

Polite vs assertive

The two modes differ in when TalkBack speaks:

• Polite waits until current speech finishes. That's the right choice for nearly everything: counters, "Saved," "3 results," "Back online."
• Assertive interrupts current speech. Use it only when the user must react now and waiting would cost them something.

An assertive alternative for the cart is justified for exactly one case, a failure that changes what the user should do next:

@Composable
fun AddToCartError(message: String?, modifier: Modifier = Modifier) {
    // The node stays composed; the live region is only switched on while there is
    // something to say, so clearing the error can't fire an empty interruption.
    Text(
        text = message.orEmpty(),
        color = MaterialTheme.colorScheme.error,
        modifier = modifier.semantics {
            if (!message.isNullOrEmpty()) liveRegion = LiveRegionMode.Assertive
        },
    )
}

“Couldn’t add to cart: only 2 left in stock” deserves to cut in. “Added to cart” never does. If you find yourself reaching for Assertive more than once or twice per app, step back. Each interruption trains users to stop trusting what TalkBack is about to say.

Notice two details. First, the Text is always in the composition and only its content changes, which is more predictable than a node that appears and disappears with its message. An empty Text has nothing to speak, so TalkBack skips it during normal navigation. Second, the assertive flag is switched on only while there's a message. Otherwise clearing the error would itself count as a change, and on some TalkBack versions an empty assertive update can interrupt current speech with nothing. Polite regions, like FormStatus below, don't need this guard, since an empty polite update interrupts nothing.

Where live regions fit

• Counters that change because of something the user did elsewhere: cart, notification count, “2 items selected.”
• Form submission results: “Order placed” (polite) or “Payment declined” (a case for assertive).
• Network status: “You’re offline. Changes will sync later” and “Back online.” Polite, and only on transitions, never on a timer.
• Async results: “12 recipes found” after a search finishes.

You don’t need one when the change happens to the node that already has focus. Part 2’s rating control, for example, announces its own new state description.

The announcement spam trap

Live regions fire on every change. Put one on a search result count, and a user typing “carbonara” hears “120 results… 48 results… 12 results… 3 results” while trying to listen to their own typing echo. The same happens with countdown timers, progress percentages, and live prices.

The fix is to announce the value only once it settles:

import androidx.compose.runtime.*
import kotlinx.coroutines.delay

/** Returns [value] only after it has stopped changing for [settleMillis]. */
@Composable
fun <T> rememberSettled(value: T, settleMillis: Long = 750L): T {
    var settled by remember { mutableStateOf(value) }
    LaunchedEffect(value) {
        delay(settleMillis)   // cancelled and restarted on every change
        settled = value
    }
    return settled
}

@Composable
fun ResultCount(count: Int, modifier: Modifier = Modifier) {
    val settledCount = rememberSettled(count)
    val spoken = pluralStringResource(R.plurals.search_results, settledCount, settledCount)

    Text(
        // Sighted users see the live value immediately...
        text = pluralStringResource(R.plurals.search_results, count, count),
        // ...TalkBack hears only the settled one.
        modifier = modifier.clearAndSetSemantics {
            contentDescription = spoken
            liveRegion = LiveRegionMode.Polite
        },
    )
}

Because LaunchedEffect(value) restarts on every change, the delay only completes once typing pauses. A screen reader user hears one sentence instead of four. For countdowns and progress, announce milestones ("1 minute left," "Upload complete") rather than every tick.

A note on View.announceForAccessibility(). It still shows up in older code, but it's deprecated as of Android 16 (API 36). Prefer live regions and pane titles, which describe state rather than firing one-off speech that services can't revisit.

Headings: a table of contents for the ear

Sighted users skim. They glance at bold section titles and jump straight to “Reviews.” TalkBack users without headings have one option: swipe through every element in order. On a long recipe screen, that can mean dozens of swipes past ingredients and steps just to reach the reviews.

Marking section titles as headings gives them the equivalent of skimming. TalkBack lets users switch navigation to “Headings” and jump section to section. The exact gesture or menu depends on the TalkBack version, but every recent version supports it.

@Composable
fun SectionHeader(text: String, modifier: Modifier = Modifier) {
    Text(
        text = text,
        style = MaterialTheme.typography.titleLarge,
        modifier = modifier
            .padding(top = 24.dp, bottom = 8.dp)
            .semantics { heading() },
    )
}

Build heading semantics into your design system’s section header component, so nobody has to remember it at each call site. Just as important, don’t build it into a general-purpose typography component like TitleText. If you do, every card title in every list becomes a heading.

What deserves heading status:

• The screen’s title. Check whether your top app bar already exposes it as a heading; if not, add it.
• Section titles that divide a long screen: Ingredients, Steps, Nutrition, Reviews.
• Group titles in settings: Notifications, Privacy, Account.

What doesn’t:

• Every card or list-item title. Forty “headings” in a product grid make heading navigation as slow as swiping.
• Bold labels, buttons, and decorative large text.
• A word that’s styled big for visual emphasis but doesn’t start a section.

A useful test: read only the headings out loud. If they sound like a table of contents for the screen, you’ve got it right.

Focus management: move people only when they’d expect it

Live regions tell users about change. Focus management moves them to it. That’s more powerful, and much more disruptive when it’s wrong.

One distinction first. FocusRequester moves input focus: the element that receives keyboard input and shows the soft keyboard. TalkBack keeps its own accessibility focus, the element it's reading. TalkBack usually follows input focus into text fields, but the two aren't the same thing. Design so that moving input focus helps, and verify on a device that TalkBack goes along with it.

On screen entry: when it helps and when it hurts

Auto-focus helps when a screen exists for typing: search, a one-time-code entry, “rename playlist.” The user arrives wanting to type.

@Composable
fun SearchField(query: String, onQueryChange: (String) -> Unit, modifier: Modifier = Modifier) {
    val focusRequester = remember { FocusRequester() }
    // Saveable: rotating the device or coming back from a result must not
    // refocus the field and pop the keyboard up again.
    var hasAutoFocused by rememberSaveable { mutableStateOf(false) }

    LaunchedEffect(Unit) {
        if (!hasAutoFocused) {
            focusRequester.requestFocus()
            hasAutoFocused = true
        }
    }

    OutlinedTextField(
        value = query,
        onValueChange = onQueryChange,
        label = { Text(stringResource(R.string.label_search_recipes)) },
        singleLine = true,
        modifier = modifier.fillMaxWidth().focusRequester(focusRequester),
    )
}

Two failure modes ship with this pattern all the time:

• Refocusing on return. With a plain LaunchedEffect(Unit) and no saved flag, the keyboard pops up every time the user navigates back to search or rotates the phone. That's annoying for everyone and disorienting for TalkBack users, whose focus is yanked away from the result they just came back to.
• Requesting focus before the target exists. If the field is composed conditionally, say after a loading state, calling requestFocus() before its focusRequester modifier is attached throws IllegalStateException. Only request focus for a node you know is in the composition.

Auto-focus hurts on long forms and content screens. A TalkBack user dropped straight into field three of a checkout form skips the page title, the instructions, and the order summary above it. They have to swipe backwards to find out where they are. On those screens, let focus start at the top as usual.

After failed validation: go to the problem

When a submit fails, moving focus to the first invalid field is the single most helpful thing you can do. Keyboard users land where they need to type, sighted users see the field scroll into view, and TalkBack usually reads the field together with its error. Part 1’s error() semantics pay off here.

enum class CheckoutField { Name, Email, Phone }

data class CheckoutFormState(
    val values: Map<CheckoutField, String> = emptyMap(),
    val errors: Map<CheckoutField, String> = emptyMap(),
    val submitAttempt: Int = 0,
)

@Composable
fun CheckoutForm(state: CheckoutFormState, onEvent: (CheckoutEvent) -> Unit) {
    val requesters = remember { CheckoutField.entries.associateWith { FocusRequester() } }

    // Keyed on the attempt counter, not the field: a second failed submit
    // on the same field must still move focus.
    LaunchedEffect(state.submitAttempt) {
        if (state.submitAttempt == 0) return@LaunchedEffect
        val firstInvalid = CheckoutField.entries.firstOrNull { it in state.errors } ?: return@LaunchedEffect
        requesters.getValue(firstInvalid).requestFocus()
    }

    Column {
        CheckoutField.entries.forEach { field ->
            ValidatedTextField( // Part 1's EmailField, generalized: icon + "Error:" text + error()
                field = field,
                value = state.values[field].orEmpty(),
                errorMessage = state.errors[field],
                onValueChange = { onEvent(CheckoutEvent.Changed(field, it)) },
                modifier = Modifier
                    .focusRequester(requesters.getValue(field))
                    .testTag(TestTags.field(field)),
            )
        }
        FormStatus(state) // see below
        Button(onClick = { onEvent(CheckoutEvent.Submit) }) {
            Text(stringResource(R.string.action_place_order))
        }
    }
}

The submitAttempt counter matters. If you key the effect on firstInvalid, the second failed submit on the same field produces the same key. The effect doesn't re-run, focus doesn't move, and the user hears nothing.

Pair the focus move with an announcement

Moving focus is not a guaranteed announcement. If input focus is already on the invalid field, which happens when the user typed in it and then double-tapped Submit, requesting focus changes nothing, and some TalkBack versions say nothing either. So combine the focus move with a short polite summary near the submit button:

@Composable
fun FormStatus(state: CheckoutFormState, modifier: Modifier = Modifier) {
    val message = if (state.submitAttempt > 0 && state.errors.isNotEmpty()) {
        pluralStringResource(R.plurals.form_errors_summary, state.errors.size, state.errors.size)
        // "Couldn't place order. %d field needs attention." / "%d fields need attention."
    } else {
        ""
    }
    Text(message, modifier = modifier.semantics { liveRegion = LiveRegionMode.Polite })
}

Keep the summary short and counted rather than repeating every error. The field-level errors are read when the user reaches each field. The summary’s only job is to make sure nobody is left wondering whether the button did anything.

Focus traps and stolen focus

• Fake dialogs. An overlay drawn with a Box on top of the screen isn't a dialog to TalkBack. Users can swipe straight past it into the content behind. Use Dialog, AlertDialog, or ModalBottomSheet. They open their own window, so accessibility focus stays inside until they're dismissed.
• Moving focus on background updates. A LaunchedEffect(items) that requests focus whenever the list refreshes pulls the user away from whatever they were reading, every time new data arrives. Focus should only move in response to the user's own action.
• Unstable list keys. When a LazyColumn reloads without stable keys, items can be recreated as new nodes, and TalkBack can lose its place and jump to the top. Give list items key = { it.id }.
• Forgetting where to return. When a dialog or sheet closes, check on a device that focus goes back to the control that opened it, not to the top of the screen.

A design checklist for dynamic UI

Most dynamic moments in an app fall into four patterns. Each has a small set of checks:

• Dialogs: Use Material’s dialog components. The title should be the first thing spoken. Every action needs a clear label: “Delete recipe,” not just “OK.” Focus should return to the trigger when the dialog closes.
• Bottom sheets: Use ModalBottomSheet for anything modal. Give a custom sheet a paneTitle so its appearance is announced. Make sure dismissing doesn't depend only on dragging: offer a labelled close action too.
• Snackbars: Material’s SnackbarHost already announces politely and stretches its timeout based on the user's accessibility timeout setting. Your job is never to put the only path to something important in a snackbar action that disappears. If "Undo" matters, offer it somewhere persistent as well.
• Loading states: Give progress indicators a label (“Loading recipes”). Announce the outcome (“12 recipes found,” “Couldn’t load recipes”), not every percentage. Don’t announce the start of a load the user didn’t trigger.

Testing what you just built

Everything in this post is visible in the semantics tree, so Part 3’s tools apply directly:

@Test
fun cartAction_isPoliteLiveRegion() {
    rule.setContent { CartAction(itemCount = 4, onOpenCart = {}) }
    rule.onNodeWithContentDescription(context.resources.getQuantityString(R.plurals.cd_cart_items, 4, 4))
        .assert(SemanticsMatcher.expectValue(SemanticsProperties.LiveRegion, LiveRegionMode.Polite))
}

@Test
fun recipeScreen_exposesExactlyItsSectionHeadings() {
    rule.setContent { AppTheme { RecipeScreen(recipe = sampleRecipe) } }
    // Catches both forgotten headings and heading inflation from a shared component.
    rule.onAllNodes(isHeading()).assertCountEquals(5) // title + 4 sections
}

@Test
fun failedSubmit_movesFocusToFirstInvalidField() {
    var state by mutableStateOf(CheckoutFormState())
    rule.setContent { CheckoutForm(state = state, onEvent = {}) }

    state = state.copy(errors = mapOf(CheckoutField.Email to "Enter a complete email address"), submitAttempt = 1)

    rule.onNodeWithTag(TestTags.field(CheckoutField.Email)).assertIsFocused()
}

Testing the timing of a live region announcement belongs in the manual routine from Part 3. Automated tests can prove the property is set. Only a person with TalkBack running can tell you whether the announcement arrives at a sensible moment.

Common mistakes

• Assertive for everything. “Saved,” “Added,” and “Loaded” are not emergencies. Interruptions should be rare enough that users never learn to ignore them.
• Heading inflation. Building heading() into a shared title style turns every card into a heading, and heading navigation becomes as slow as swiping. Test with assertCountEquals.
• Stealing focus after the user has started. Auto-focus on return, focus moves on data refresh, and dialogs that pop up mid-task all yank TalkBack users away from what they were doing. Move focus only in response to the user’s own action, or once on first entry to a screen built for typing.
• Announcing every tick. Live regions on raw, fast-changing values (search counts, timers, progress) turn TalkBack into a stream of numbers. Settle first, then announce.

Up next

There’s one more dimension of inclusion left, and it has nothing to do with screen readers: direction. Hundreds of millions of people read right to left. Part 5, Going Global, covers:

• what Compose mirrors for you automatically, and what it can’t
• why some icons must flip and others must never flip
• how to audit every screen in a single pass

It closes the series with one combined release checklist covering accessible, testable, and RTL-ready.

📱 Crack Your Next Android Interview

If you’re targeting a senior Android role at a FAANG or top-tier MNC, syntax knowledge alone won’t get you through the loop. I highly recommend “Cracking Top MNC Android Interviews” — a senior-level playbook covering framework internals, Jetpack Compose, coroutines, Android-specific system design, and DSA reframed around real mobile constraints, to help you walk into bar-raiser rounds ready.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover.

Originally published on Medium.

Previously: Part 1 (“Raising the Floor”) set the baseline rules, and Part 2 (“From Five Stars to One Sentence”) built a custom rating control with real semantics. This part makes sure none of that quietly breaks.

TL;DR Accessibility regressions don’t crash, don’t change a single pixel, and don’t fail a single existing test. You catch them by testing the semantics tree*, in five layers:*

1. Targeted assertions on the nodes that matter.
2. Bulk assertions across groups of nodes.
3. Touch-size checks.
4. Automated audits with Google’s Accessibility Test Framework (ATF).
5. A short manual TalkBack routine for everything machines can’t judge.

Each layer catches what the one below it can’t.

The regression nobody noticed

Here’s a migration that happens in real codebases. The design system team ships a new AppIconButton to replace scattered IconButton usages. It looks like this:

@Composable
fun AppIconButton(icon: ImageVector, onClick: () -> Unit, modifier: Modifier = Modifier) {
    IconButton(onClick = onClick, modifier = modifier) {
        Icon(icon, contentDescription = null) // "the caller can add semantics if needed"
    }
}

Forty call sites are migrated in one pull request, and the review approves it. Everything checks out:

• The compiler is happy: no call site passes a description, because there’s no parameter for one.
• Screenshot tests pass, because the pixels are identical.
• Unit tests pass, because none of them ever looked at labels.

Three weeks later, a screen reader user writes in: the share, save, and delete buttons all say “Unlabeled, button.”

That’s why accessibility needs its own tests. Every check you already run looks at pixels or behavior. TalkBack reads neither. It reads the semantics tree. So that’s what the tests have to read too.

The fix for AppIconButton is a required contentDescription: String? parameter, with no default, so every caller has to decide. The protection is the test layers below.

Layer 1: Targeted semantics assertions

Start with the nodes that carry the most risk: primary actions, custom controls, and anything a redesign is likely to touch. Compose UI tests find nodes by semantics, so the test reads the same tree TalkBack does.

One rule before any code: never hard-code visible strings in tests. "Save recipe" breaks the day someone edits the copy, and it means you can never run the suite in another locale. Resolve strings from resources the same way the app does:

private val context: Context = ApplicationProvider.getApplicationContext()
private fun str(@StringRes id: Int, vararg args: Any): String = context.getString(id, *args)

Now assert what TalkBack depends on:

class RecipeHeaderA11yTest {

    @get:Rule val rule = createComposeRule()

    @Test
    fun header_exposesHeadingAndLabelledActions() {
        rule.setContent { AppTheme { RecipeHeader(recipe = sampleRecipe, onSave = {}, onShare = {}) } }

        rule.onNode(hasText(sampleRecipe.title) and isHeading())
            .assertIsDisplayed()

        rule.onNodeWithContentDescription(str(R.string.cd_save_recipe, sampleRecipe.title))
            .assertIsDisplayed()
            .assertHasClickAction()

        rule.onNodeWithContentDescription(str(R.string.cd_share_recipe, sampleRecipe.title))
            .assertHasClickAction()
    }
}

(Heading semantics are the subject of Part 4. Here we only check they exist.)

The real payoff comes with custom controls. Part 2’s RatingStars made promises in its semantics: one node, a state description, a range, and actions that keep the spoken value in sync. Each promise becomes an assertion:

class RatingStarsA11yTest {

    @get:Rule val rule = createComposeRule()

    private val label get() = str(R.string.label_recipe_rating)

    @Test
    fun rating_isOneAdjustableNodeWithSpokenValue() {
        rule.setContent { RatingStars(rating = 3, onRatingChange = {}, label = label) }

        rule.onNodeWithContentDescription(label)
            .assert(hasStateDescription(str(R.string.rating_state, 3, 5)))
            .assert(hasProgressBarRangeInfo(ProgressBarRangeInfo(3f, 0f..5f, steps = 4)))
            .assert(SemanticsMatcher.keyIsDefined(SemanticsActions.SetProgress))
    }

    @Test
    fun increaseAction_updatesStateAndSpokenValue() {
        var rating by mutableIntStateOf(3)
        rule.setContent { RatingStars(rating = rating, onRatingChange = { rating = it }, label = label) }

        rule.onNodeWithContentDescription(label)
            .performCustomAccessibilityActionWithLabel(str(R.string.rating_action_increase))

        assertEquals(4, rating)
        rule.onNodeWithContentDescription(label)
            .assert(hasStateDescription(str(R.string.rating_state, 4, 5)))
    }

    @Test
    fun increaseAction_isNotOfferedAtMaximum() {
        rule.setContent { RatingStars(rating = 5, onRatingChange = {}, label = label) }

        rule.onNodeWithContentDescription(label)
            .assert(!hasCustomAction(str(R.string.rating_action_increase)))
    }
}

fun hasCustomAction(label: String) = SemanticsMatcher("has custom action \"$label\"") { node ->
    node.config.getOrNull(SemanticsActions.CustomActions).orEmpty().any { it.label == label }
}

The second test is the one that pays for itself. It invokes the action the way an accessibility service would, then checks two things:

• The state changed. This catches callbacks that were never hoisted.
• The spoken state changed. This catches Part 2’s stale remember { } trap.

A tap-based test catches neither.

Layer 2: Bulk assertions

Targeted tests protect the nodes you thought about. Bulk tests protect the ones you didn’t, like every product image in a grid or every icon button in a toolbar. Use test tags to select the group:

AsyncImage(
    model = product.imageUrl,
    contentDescription = product.altText ?: product.name,
    modifier = Modifier.testTag(TestTags.PRODUCT_IMAGE),
)

Then make the check reusable. There are two traps in this helper, and both cause false greens, meaning the test passes when it shouldn’t:

fun SemanticsNodeInteractionsProvider.assertAllHaveDescriptions(tag: String, minimumCount: Int = 1) {
    // Trap 1: tagged images inside a clickable card are merged into the card.
    // In the default (merged) tree, the tagged node doesn't exist on its own.
    val nodes = onAllNodesWithTag(tag, useUnmergedTree = true)

    // Trap 2: assertAll on an empty collection passes. Prove the nodes exist first.
    val found = nodes.fetchSemanticsNodes().size
    assertTrue(found >= minimumCount, "Expected at least $minimumCount nodes tagged '$tag', found $found")

    nodes.assertAll(hasMeaningfulContentDescription())
}

fun hasMeaningfulContentDescription() = SemanticsMatcher("has a meaningful contentDescription") { node ->
    val placeholders = setOf("image", "icon", "photo", "picture")
    node.config.getOrNull(SemanticsProperties.ContentDescription).orEmpty()
        .any { it.isNotBlank() && it.trim().lowercase() !in placeholders }
}

SemanticsMatcher.keyIsDefined(ContentDescription) alone isn't enough: an empty string "" or a lazy "image" passes it. The custom matcher rejects both.

Usage is one line per group:

@Test
fun productGrid_everyImageIsDescribed() {
    rule.setContent { AppTheme { ProductGrid(products = sampleProducts, onOpen = {}) } }
    rule.assertAllHaveDescriptions(TestTags.PRODUCT_IMAGE, minimumCount = sampleProducts.size)
}

One more caution about lazy layouts. LazyVerticalGrid only composes the items that are visible. With twenty products, the test above checks perhaps six of them. Either feed the test a small dataset that fits on screen, or scroll with performScrollToIndex and assert in batches.

Layer 3: Touch target checks

Part 1’s 48dp rule becomes an assertion:

@Test
fun toolbarActions_meetMinimumTouchSize() {
    rule.setContent { AppTheme { RecipeToolbar(onBack = {}, onSave = {}, onShare = {}) } }

    val clickables = rule.onAllNodes(hasClickAction())
    val count = clickables.fetchSemanticsNodes().size
    assertTrue(count > 0, "No clickable nodes found")

    repeat(count) { index ->
        clickables[index]
            .assertTouchWidthIsAtLeast(48.dp)
            .assertTouchHeightIsAtLeast(48.dp)
    }
}

Both assertions are part of androidx.compose.ui.test and run against a SemanticsNodeInteraction inside a Compose UI test. They are not runtime modifiers. They measure a node's touch bounds, which aren't always the same as its layout bounds. ATF (Layer 4) measures the bounds Android reports to accessibility services. If the two layers ever disagree about a control, trust the stricter one and fix the layout, as Part 1 did with sizeIn(minWidth = 48.dp, minHeight = 48.dp). That version satisfies both.

Layer 4: Automated framework checks

Layers 1 to 3 check what you thought to assert. The Accessibility Test Framework (ATF), the same engine behind Accessibility Scanner, checks what you didn’t. It runs a catalogue of rules against the live accessibility tree.

On Compose 1.8 and later, ATF is wired into Compose tests through a separate artifact:

// build.gradle.kts
androidTestImplementation("androidx.compose.ui:ui-test-junit4-accessibility:<compose-version>")

class RecipeScreenAuditTest {

    // Accessibility checks need a real Activity behind the composition.
    @get:Rule val rule = createAndroidComposeRule<ComponentActivity>()

    @Before
    fun enableChecks() {
        rule.enableAccessibilityChecks()
    }

    @Test
    fun recipeScreen_passesAutomatedAudit() {
        rule.setContent { AppTheme { RecipeScreen(recipe = sampleRecipe) } }
        rule.onRoot().tryPerformAccessibilityChecks()
    }
}

Once enabled, checks also run when your tests perform actions like performClick(). That means every existing interaction test becomes an accessibility audit at no extra cost.

For View-based or hybrid screens tested with Espresso, the equivalent switch is set once per test class. setRunChecksFromRootView(true) audits the whole window, not just the view being acted on:

companion object {
    @BeforeClass @JvmStatic
    fun enableAccessibilityChecks() {
        AccessibilityChecks.enable()
            .setRunChecksFromRootView(true)
            .setSuppressingResultMatcher(
                // Narrow, documented, temporary: one check, one view, one ticket.
                allOf(
                    matchesCheck(TextContrastCheck::class.java),
                    matchesViews(withId(R.id.legacy_promo_banner)), // A11Y-412, remove by Q1
                ),
            )
    }
}

What ATF catches well:

• missing labels on things people can act on
• touch targets that are too small
• duplicate or redundant descriptions (a description that says “button” on a button)
• low contrast
• clickable elements stacked on top of each other

Contrast results depend on ATF capturing a screenshot, so keep Part 1’s theme contrast test as your main contrast guard.

What ATF can’t catch: whether a label makes sense, whether the reading order matches the intent, whether focus lands somewhere sensible after an error, and whether a custom control can actually be operated. A label of "btn_2" passes every automated check ever written.

Layer 5: Manual testing

Automated layers protect the floor. Only people can judge the experience. Keep the manual part small enough that it actually happens on every release: ten minutes, one critical flow, every release candidate.

1. Linear swipe (minutes 0–2). Swipe through the flow from start to finish with TalkBack’s speech output shown on screen. Listen for “Unlabeled,” duplicated phrases, and moments where you lose track of where you are.
2. Operate, don’t just listen (2–4). Use every custom control with adjust gestures and the Actions menu only. No sighted shortcuts.
3. Break something (4–6). Submit an invalid form and trigger a loading state. Is the error spoken? Does the result get announced? (That’s Part 4.)
4. Scale up (6–8). Set the largest font size and display size. Look for clipped text, overlapping controls, and buttons pushed off screen.
5. Scan (8–10). Run Accessibility Scanner on each screen in the flow. It’s ATF with a UI, and it catches things on real data that your test fixtures never contain.

Involve real users at least once per major feature. Five sessions with people who use TalkBack, Switch Access, or magnification every day will teach you more than months of internal testing. Pay them for their time, give them tasks (“reorder last week’s groceries”) rather than asking “is this accessible?”, and watch quietly.

Putting tests in CI

Split the layers by cost so the fast ones run on every change:

• On every pull request: Layers 1 to 3. Semantics and touch-size assertions run on the JVM with Robolectric, so they take seconds and need no device. This is where the AppIconButton regression gets stopped.
• On merge or nightly: Layer 4 on an emulator. Gradle Managed Devices give you the same emulator image every run, without anyone looking after a device farm.
• Before release: Layer 5, the manual routine, run by a person and signed off in the release checklist.

Keeping them stable:

• Disable animations in testOptions.
• Pin font scale, locale, and display size per run, so ATF results don’t drift between machines.
• Use fixed fixtures instead of live network data.

Triage every failure into one of three buckets:

• Regression: blocks the merge. No exceptions.
• Known issue: suppress it narrowly. One check, one element, a ticket number, and a date to remove it, as in the Espresso snippet above. A broad suppression like “ignore all contrast checks” is how a suite slowly stops protecting anything.
• False positive: suppress it with a comment explaining why it’s wrong, so the next person doesn’t re-litigate it.

Common mistakes

• Treating a passing audit as proof of accessibility. ATF proves that labels exist, not that they’re right. A screen can pass every check and still be unusable with TalkBack. Layer 5 isn’t optional.
• Finding nodes by visible text. onNodeWithText("Add to cart") breaks when the copy changes, and it ties the suite to one locale forever. Use string resources, test tags, and semantics matchers.
• False greens. assertAll over an empty collection, tagged nodes searched in the merged tree, and lazy lists that compose six of twenty items all pass. Assert counts before asserting properties.
• Testing taps instead of actions. performClick() on a star proves the star works for sighted users. performCustomAccessibilityActionWithLabel proves it works for everyone else.

Up next

Everything so far has been about screens that sit still. Real apps change constantly: a badge updates, a form fails validation, a result loads three seconds later. Part 4, Announcing, Navigating, and Focusing, covers three things:

• live regions, which announce changes without stealing focus
• heading semantics, which let users jump between sections
• deliberate focus management, which puts focus where the user needs it after an error

It also shows how to test all three with what you learned here.

📱 Go Beyond Using AI — Learn How to Actually Build It Into Your Android Apps

If you’re building Android apps in 2026, “adding AI” can’t just mean bolting on a chatbot API — it means understanding on-device inference, model trade-offs, and production realities well enough to ship a feature users actually trust. I highly recommend “Mastering Android AI: App to Intelligence” It’s a practical, code-first journey through the entire Android AI stack — from ML Kit and LiteRT to Gemma, Gemini, and MediaPipe — covering everything from your first “hello inference” screen to thermal throttling, model drift monitoring, and full applied projects like an AI-powered camera app and a health companion, with hands-on Kotlin builds at every step.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover

Originally published on Medium.

Previously: Part 1 (“Raising the Floor”) covered the five baseline rules every screen must pass. Those rules assume standard components. This part is about the ones you build yourself.

TL;DR Material components ship with semantics. Your custom components ship with none until you add them. The semantics tree, not the pixels, is what TalkBack reads. Making a custom control accessible comes down to four moves:

• Collapse it into one node: merge descendants for things people read, and clear and replace them for things people operate.
• Say what it is (contentDescription) separately from what it currently holds (stateDescription).
• Pick an interaction model that matches how the control behaves.
• Expose actions so nobody has to hit a 20dp star precisely.

The five-stars problem

Picture a recipe app with a “Rate this recipe” row: five stars, tap one to set your score. It looks great and works perfectly with a finger. Here’s the code, which you’ll find in some form in a lot of codebases:

// ❌ To TalkBack, this is five unrelated buttons
@Composable
fun NaiveRating(rating: Int, onRatingChange: (Int) -> Unit) {
    Row {
        for (star in 1..5) {
            Icon(
                painter = painterResource(
                    if (star <= rating) R.drawable.ic_star_filled else R.drawable.ic_star_outline,
                ),
                contentDescription = "Star",
                modifier = Modifier
                    .size(32.dp)
                    .clickable { onRatingChange(star) },
            )
        }
    }
}

Now turn on TalkBack and swipe through it. You hear “Star, button” five times. You aren’t told which stars are filled, what the control is for, or what the current score is. If someone “fixed” the hard-coded string by passing null, it gets worse: five "Unlabeled, button" stops in a row.

What a screen reader user needs is one stop and one sentence: “Recipe rating, 3 of 5 stars, slider,” plus a way to change the value without hunting for a 32dp target.

Getting from the first version to the second takes three steps. First, a short look at the data structure all three steps edit.

Semantics 101: the tree TalkBack actually reads

As Compose builds your UI tree, it also builds a parallel semantics tree. That tree only has nodes where something carries meaning: text, a description, a role, a state, or an action someone can perform. TalkBack, Switch Access, Voice Access, autofill, and your UI tests all read this tree. None of them see your pixels.

The tree comes in two views:

• Unmerged is every semantics node exactly as each composable declared it.
• Merged is what accessibility services work with. A node marked mergeDescendants = true absorbs its descendants' properties and becomes a single focus stop.

Many stock components merge for you. Button, IconButton, ListItem, and any element using Modifier.clickable or Modifier.toggleable do this, which is why a Material button containing an icon and a label reads as one thing.

You can inspect both views in two ways:

• Layout Inspector in Android Studio. Select a composable and its attributes panel lists the semantics it declares and the semantics it ends up with after merging.
• A test or debug harness, which dumps the whole tree to Logcat:

composeTestRule.onRoot().printToLog("A11Y")                       // merged: what TalkBack sees
composeTestRule.onRoot(useUnmergedTree = true).printToLog("A11Y") // as each composable declared it

A useful rule of thumb: if a node in the merged tree doesn’t read like something you’d say out loud, TalkBack won’t say it well either.

Step 1: Collapse the control into one node

Merge things people read

Start with the read-only case: a review header with an avatar, the reviewer’s name, a star strip, and a timestamp. It should be one stop, not four.

<string name="rating_display">Rated %1$d out of %2$d</string>

private const val MAX_STARS = 5

@Composable
fun ReviewHeader(review: Review, modifier: Modifier = Modifier) {
    // semantics { } is not a composable scope, so resolve strings before entering it.
    val starsLabel = stringResource(R.string.rating_display, review.stars, MAX_STARS)

    Row(
        modifier = modifier.semantics(mergeDescendants = true) { },
        verticalAlignment = Alignment.CenterVertically,
    ) {
        AsyncImage( // Coil
            model = review.authorPhotoUrl,
            contentDescription = null, // decorative: the name sits right next to it
            modifier = Modifier.size(40.dp).clip(CircleShape),
        )
        Column(Modifier.padding(start = 12.dp)) {
            Text(review.authorName, style = MaterialTheme.typography.titleSmall)
            StarStrip(
                filled = review.stars,
                modifier = Modifier.semantics { contentDescription = starsLabel },
            )
            Text(review.postedLabel, style = MaterialTheme.typography.bodySmall)
        }
    }
}

The star strip itself draws icons and nothing else:

@Composable
private fun StarStrip(filled: Int, modifier: Modifier = Modifier) {
    Row(modifier) {
        repeat(MAX_STARS) { index ->
            Icon(
                painter = painterResource(
                    if (index < filled) R.drawable.ic_star_filled else R.drawable.ic_star_outline,
                ),
                contentDescription = null, // the strip speaks for all five
                modifier = Modifier.size(16.dp),
            )
        }
    }
}

Why do the child icons get null? Because merging collects. It doesn't summarize or remove duplicates. If each star kept a "Star" description, the merged node would carry the strip's label and five more stars, and TalkBack would read all of them. After merging, the parent is the only one who should speak.

The merged node ends up with the two Text values and the strip's content description, so TalkBack reaches the whole header in one stop. Merged nodes keep text and content descriptions as separate lists, and the way TalkBack joins them can differ slightly between versions. Listen to the final phrasing once on a device rather than assuming it.

Clear and replace for things people operate

Merging has a limit, and it shows up the moment the children are interactive. A child that is itself clickable, toggleable, or otherwise merging stays its own focus stop. Wrap NaiveRating in semantics(mergeDescendants = true) and nothing changes: TalkBack still finds five buttons.

When the visual parts of an input control mean nothing on their own, replace them. clearAndSetSemantics throws away every descendant's semantics and lets you declare the node's entire accessible identity. Touch input on the children keeps working exactly as before. Only what assistive technology sees changes.

Row(
    modifier = Modifier.clearAndSetSemantics {
        // Everything TalkBack knows about this control is declared here, and only here.
    },
) {
    // five tappable stars, invisible to accessibility services
}

The trade-off: you now own everything. Anything you don’t declare doesn’t exist. That includes the label, the value, the role, and every way to operate the control. Steps 2 and 3 fill those in.

Step 2: Say what it is, then what it holds

Two properties do two different jobs:

• contentDescription is identity. It's stable for the life of the screen: "Recipe rating."
• stateDescription is the current value. It changes as the user acts: "Not rated," "3 of 5 stars."

It’s tempting to cram both into one string, "Recipe rating, 3 of 5 stars". Keep them apart instead, for three reasons:

1. When the focused node’s state description changes, TalkBack can announce the new value without re-reading the label.
2. Tests (Part 3) can assert on the value directly.
3. Translators get two clean strings instead of one concatenation.

Choosing the interaction model

The role question is really a question about how the control behaves. For star ratings there are three honest options.

• Read-only display. One node with a description and no actions. Use this for averages on product cards. Don’t make it look tappable if it isn’t.
• Radio group. Put Modifier.selectableGroup() on the row and Modifier.selectable(selected = ..., role = Role.RadioButton) on each star. This allows direct selection, but it costs five focus stops. It also creates a quiet mismatch: three stars look filled while only one is selected. Radio groups suit small sets of choices with no order, like S/M/L, much better than ordered scales.
• Adjustable value. One node that declares a range and a setProgress action. This is exactly how Material's own Slider presents itself: it sets no role at all, and Compose exposes it to Android as a seek bar. It gives users one stop, and it matches what a rating actually is, a point on an ordered scale.

For rating input, the adjustable model wins. Its one weakness is that adjust gestures are invisible to people who don’t already know them. Step 3 fixes that.

Modifier.clearAndSetSemantics {
    contentDescription = label
    stateDescription = stateText
    progressBarRangeInfo = ProgressBarRangeInfo(
        current = rating.toFloat(),
        range = 0f..maxRating.toFloat(),
        steps = maxRating - 1, // whole stars only: 1, 2, 3, 4 sit between the ends
    )
    setProgress { target ->
        val next = target.roundToInt().coerceIn(0, maxRating)
        if (next != rating) onRatingChange(next)
        true
    }
}

Three details here matter in production:

• Without stateDescription, the value is spoken as a percentage. Compose falls back to describing a range by its percentage, so a 3-star rating would come out as "60 percent." Your state description replaces that with the words people actually use.
• steps controls how far one adjustment moves the value. When a node exposes both a range and setProgress, Compose also offers the platform's scroll-forward and scroll-backward actions. TalkBack's adjust gestures use those, moving by one step. With steps = maxRating - 1, one step is exactly one star. Leave steps at 0 and the range is treated as continuous, so each adjustment moves by a small fraction of a star.
• setProgress must snap. Assistive technology can request any float value. Round it and clamp it to the range yourself rather than trusting the caller.

Step 3: Custom actions, for people who can’t aim

Adjust gestures exist, but plenty of TalkBack users never learn them. Switch Access and Voice Access users depend on named actions. CustomAccessibilityAction adds named commands to the node, which TalkBack lists in its Actions menu and other services expose in their own way.

<string name="rating_action_increase">Increase rating</string>
<string name="rating_action_decrease">Decrease rating</string>
<string name="rating_action_clear">Clear rating</string>

customActions = buildList {
    if (rating < maxRating) {
        add(CustomAccessibilityAction(increaseLabel) { onRatingChange(rating + 1); true })
    }
    if (rating > 0) {
        add(CustomAccessibilityAction(decreaseLabel) { onRatingChange(rating - 1); true })
        add(CustomAccessibilityAction(clearLabel) { onRatingChange(0); true })
    }
}

The lambda returns a Boolean. true means "handled." false tells the accessibility service the action didn't happen, and the service may give the user failure feedback. The better pattern, shown above, is to offer only the actions that can succeed right now. There's no "Increase rating" at five stars, so a user can never pick an action that silently does nothing.

This step isn’t polish. Once you’ve called clearAndSetSemantics, the individual stars are invisible to TalkBack. Exploring by touch lands on the whole control, not on star four. For anyone using assistive technology, adjust gestures and named actions are now the only ways to change the value. That's exactly why both must exist.

The stale-state trap

Here’s a bug that survives code review because the screen looks correct:

// ❌ Computed once on first composition, never again
val context = LocalContext.current
val stateText = remember { context.getString(R.string.rating_state, rating, maxRating) }

The user picks “Increase rating.” The parent updates its state, the stars repaint, and TalkBack still says “3 of 5 stars.” What the screen shows and what TalkBack says have drifted apart, and only screen reader users notice. Derive the description from current state on every composition (stringResource is cheap). If you really must cache it, key the cache: remember(rating, maxRating) { ... }.

A related version of the same bug: a caller passes onRatingChange = {} while wiring things up, the stars appear to work in a preview because the preview owns its own state, and the action does nothing in the real screen. Hoist the state, and test the action, not just the tap. Part 3 shows how.

Putting it together

Here’s the complete control. Every line maps to one of the steps above.

<string name="rating_state">%1$d of %2$d stars</string>
<string name="rating_state_none">Not rated</string>
<string name="label_recipe_rating">Recipe rating</string>

@Composable
fun RatingStars(
    rating: Int,
    onRatingChange: (Int) -> Unit,
    label: String,
    modifier: Modifier = Modifier,
    maxRating: Int = 5,
    enabled: Boolean = true,
) {
    // Step 2: state is derived on every composition, never cached without a key.
    val stateText = if (rating == 0) {
        stringResource(R.string.rating_state_none)
    } else {
        stringResource(R.string.rating_state, rating, maxRating)
    }
    val increaseLabel = stringResource(R.string.rating_action_increase)
    val decreaseLabel = stringResource(R.string.rating_action_decrease)
    val clearLabel = stringResource(R.string.rating_action_clear)

    Row(
        // Step 1: one node; the stars below contribute nothing to semantics.
        modifier = modifier.clearAndSetSemantics {
            contentDescription = label
            stateDescription = stateText
            progressBarRangeInfo = ProgressBarRangeInfo(
                current = rating.toFloat(),
                range = 0f..maxRating.toFloat(),
                steps = (maxRating - 1).coerceAtLeast(0),
            )
            if (enabled) {
                setProgress { target ->
                    val next = target.roundToInt().coerceIn(0, maxRating)
                    if (next != rating) onRatingChange(next)
                    true
                }
                // Step 3: only actions that can succeed right now.
                customActions = buildList {
                    if (rating < maxRating) {
                        add(CustomAccessibilityAction(increaseLabel) { onRatingChange(rating + 1); true })
                    }
                    if (rating > 0) {
                        add(CustomAccessibilityAction(decreaseLabel) { onRatingChange(rating - 1); true })
                        add(CustomAccessibilityAction(clearLabel) { onRatingChange(0); true })
                    }
                }
            } else {
                disabled()
            }
        },
    ) {
        for (star in 1..maxRating) {
            val filled = star <= rating
            Box(
                modifier = Modifier
                    .size(48.dp)  // Part 1, Rule 2: 48dp touch target per star
                    .clip(CircleShape)
                    .clickable(enabled = enabled) {
                        // Tapping the current top star again clears the rating.
                        onRatingChange(if (star == rating) 0 else star)
                    },
                contentAlignment = Alignment.Center,
            ) {
                Icon(
                    // Part 1, Rule 4: filled vs outline differ in shape, not only color.
                    painter = painterResource(
                        if (filled) R.drawable.ic_star_filled else R.drawable.ic_star_outline,
                    ),
                    contentDescription = null,
                    tint = if (filled) {
                        MaterialTheme.colorScheme.primary
                    } else {
                        MaterialTheme.colorScheme.onSurfaceVariant
                    },
                    modifier = Modifier.size(28.dp),
                )
            }
        }
    }
}

Using it looks like any other state-hoisted control:

var rating by rememberSaveable { mutableIntStateOf(0) }

RatingStars(
    rating = rating,
    onRatingChange = { rating = it },
    label = stringResource(R.string.label_recipe_rating),
)

Before and after, as a TalkBack user experiences it:

• Before: five stops, each “Star, button.” The score is never spoken, and the control’s purpose is never stated.
• After, on focus: one stop, “Recipe rating, Not rated, slider,” followed by TalkBack’s usage hint.
• After an adjust gesture or “Increase rating”: “1 of 5 stars.”
• After “Clear rating” from the Actions menu: “Not rated.”

Exact wording, like whether the role is spoken as “slider” or “seek control,” depends on the TalkBack version. The structure is what matters.

Keyboard note. The stars are hidden from TalkBack, but their clickable modifiers still accept keyboard focus. On tablets and Chromebooks with a hardware keyboard, that means five Tab stops and no arrow-key adjustment. If keyboard users matter to your app, give the stars focusProperties { canFocus = false }, make the row focusable, and handle left and right arrow keys there. Part 4 covers focus in depth.

A reusable pattern for any custom control

The rating control is just one example. The same five questions work for any custom component you build:

1. What’s the unit? Merge things people read. Clear and replace things people operate.
2. What is it? A stable contentDescription, or the label from a role-bearing modifier.
3. What does it hold right now? A stateDescription, plus the platform's own notion of state where one exists: toggleableState, selected, or a range.
4. How is it operated without precision? Use built-in actions first (onClick, setProgress, scrolling), then custom actions for everything else.
5. Does the spoken state change when the pixels do? If you can’t answer that with a test, you don’t know.

One more rule: reach for the semantic modifier before hand-rolling semantics. Modifier.toggleable(value, role = Role.Switch, onValueChange = ...) gives you the role, the on/off state, and the click action in one line. Write custom semantics only for what the stock modifiers can't express.

Common mistakes

• Merging without silencing children. The parent gets a good label, but each child icon keeps its own description, so TalkBack reads the summary and then “Star, Star, Star, Star, Star.” After merging, children that are only visual get contentDescription = null.
• Actions that change state but not the spoken state. This usually comes from a description cached with remember { } and no key, or a callback that was never hoisted. The screen updates and the speech doesn't.
• A role that contradicts behavior. Role.Button on an adjustable control makes TalkBack promise "double-tap to activate," and then nothing happens. Radio buttons on an ordered scale confuse which stars are "selected." If the role tells the user what gesture to use, that gesture must work.
• Clearing semantics and forgetting to put anything back. After clearAndSetSemantics, a control with no setProgress, no onClick, and no custom actions can be focused but never operated.

Up next

Every property we declared here (the content description, the state, the range, the actions) can be queried, which means it can be tested. Part 3, Testing Accessibility, turns this post into CI checks:

• asserting state descriptions
• invoking custom actions from a test
• enforcing 48dp targets
• letting Google’s Accessibility Test Framework catch what you forgot

It also covers what no automated check can catch, and why the manual TalkBack routine from Part 1 still earns its ten minutes per release.

🔐 Go Beyond Using Android — Master How It’s Actually Secured

If you’re building, testing, or breaking Android apps, understanding the security model beneath the SDK separates developers who follow best practices from those who truly understand why those practices exist. I highly recommend “Mastering Android Security: From Fundamentals to Advanced Practice.” It’s a comprehensive, architecture-first journey through app sandboxing, cryptography, network defense, reverse engineering, and exploitation — spanning everything from AndroidManifest.xml internals to TrustZone and the Verified Boot chain, with hands-on labs at every step.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover

Originally published on Medium.

TL;DR Accessibility doesn’t start with exotic APIs. It starts with five properties every screen must have: meaningful labels, 48dp touch targets, readable contrast, meaning that survives without color, and a reading order that matches intent. Each one is cheap to get right on day one and expensive to retrofit later. This post shows the idiomatic Compose way to do each, plus the specific ways each one breaks in production.

The bug report that wasn’t a crash

Imagine a release that looks perfect on every dashboard. Crash-free sessions above 99.9%, ANRs flat, conversion steady. Two weeks later a support ticket arrives: “I can’t find how to pay.” The user relies on TalkBack. During a redesign, the checkout entry point became an Icon with Modifier.clickable and no description. TalkBack announced it as "Unlabeled, double-tap to activate." Nothing threw. No metric moved. A paying customer simply could not pay.

That’s the defining property of accessibility bugs: they fail silently, and only for the people least able to work around them.

The audience is wider than “screen reader users.” It includes people with low vision who run at 200% font scale, the roughly one in twelve men with some form of color-vision deficiency, people with tremors, and every user who has ever squinted at a phone in direct sunlight or used it one-handed on a crowded train.

There’s a business and legal side too. The European Accessibility Act has applied to many consumer-facing digital products and services in the EU since June 2025, accessibility claims against mobile apps are routine in the US, and Google Play’s pre-launch report already flags accessibility issues on your builds. But the strongest argument is the simplest: an app that some people cannot use is, for them, a broken app.

Here are the five rules that form the floor.

Rule 1: Every interactive element has a meaningful label

When a clickable node has no text, no contentDescription, and nothing merged in from its children, TalkBack has nothing meaningful to say. It falls back to the role and "Unlabeled," as in "Unlabeled, button." A label should describe what the thing is and its current state, not what it looks like.

Generic: “Cart.” Useful: “Shopping cart, 3 items.”

<!-- res/values/strings.xml -->
<string name="cd_cart_empty">Shopping cart, empty</string>
<plurals name="cd_cart_items">
    <item quantity="one">Shopping cart, %d item</item>
    <item quantity="other">Shopping cart, %d items</item>
</plurals>

@Composable
fun CartAction(itemCount: Int, onOpenCart: () -> Unit) {
    // English ignores quantity="zero", so the empty state needs its own string.
    val description = if (itemCount == 0) {
        stringResource(R.string.cd_cart_empty)
    } else {
        pluralStringResource(R.plurals.cd_cart_items, itemCount, itemCount)
    }

    IconButton(onClick = onOpenCart) {
        BadgedBox(
            badge = {
                if (itemCount > 0) {
                    // The icon label already carries the count. Without this, IconButton
                    // merges the badge text too: "Shopping cart, 3 items, 3".
                    Badge(modifier = Modifier.clearAndSetSemantics { }) {
                        Text(itemCount.toString())
                    }
                }
            },
        ) {
            Icon(Icons.Outlined.ShoppingCart, contentDescription = description)
        }
    }
}

Three production failure modes worth knowing:

1. String concatenation. "Cart, " + count + " items" ships English to your Arabic users and breaks pluralization in languages with more than two plural forms. Always go through resources.
2. The silent quantity="zero". In English, Android selects plural forms by grammatical category, not literal value, so a zero item is never chosen. Teams discover this when TalkBack reads "Shopping cart, 0 items" in a locale they never tested.
3. Leaky merges. Clickable containers merge their children’s semantics. Anything visible inside, like badges, prices, or “NEW” chips, gets appended to the announcement unless you deliberately clear it.

Decorative vs informative images

If removing an image loses no information, it’s decorative. Pass null so TalkBack skips it entirely:

Image(
    painter = painterResource(R.drawable.header_wave),
    contentDescription = null, // pure ornament: skip it
    modifier = Modifier.fillMaxWidth(),
)

If the image carries information, like a product photo, describe it. Prefer alt text from your backend, and fall back to something human rather than a filename:

AsyncImage( // Coil
    model = product.imageUrl,
    contentDescription = product.altText ?: product.name,
)

A related rule: an Icon sitting next to a Text inside a Button should have contentDescription = null. The text is already the label; describing the icon too produces "Download, Download."

Rule 2: Touch targets are at least 48dp × 48dp

Small targets punish users with tremors, limited dexterity, or large fingers, and anyone tapping while walking. The key insight is that the visual size and the touch size are independent. Your designer’s 18dp info glyph can stay 18dp; its hit area cannot.

Here’s the bug as it usually appears in a code review:

// ❌ 18dp visual AND 18dp touch area
Icon(
    imageVector = Icons.Outlined.Info,
    contentDescription = stringResource(R.string.cd_more_info),
    modifier = Modifier
        .size(18.dp)
        .clickable(onClick = onClick),
)

And the fix, which separates the two sizes explicitly:

@Composable
fun InlineInfoButton(onClick: () -> Unit, modifier: Modifier = Modifier) {
    Box(
        modifier = modifier
            .sizeIn(minWidth = 48.dp, minHeight = 48.dp) // touch area
            .clip(CircleShape)                           // 48dp circular ripple, like IconButton
            .clickable(role = Role.Button, onClick = onClick),
        contentAlignment = Alignment.Center,
    ) {
        Icon(
            imageVector = Icons.Outlined.Info,
            contentDescription = stringResource(R.string.cd_more_info),
            modifier = Modifier.size(18.dp), // visual size
        )
    }
}

If you’re on Material 3, Modifier.minimumInteractiveComponentSize() does the same job and is what IconButton, Checkbox, and friends use internally. Prefer the stock components where they fit; reach for the modifier when you build your own.

Two subtler failure modes:

• Modifier order shrinks hit areas. Modifier.padding(12.dp).clickable { } makes the padding untappable, because clickable only sees the space left after padding. If the padding should be tappable, put clickable first.
• “Dense mode” overrides. Teams squeezing toolbars sometimes provide a zero or unspecified value for LocalMinimumInteractiveComponentSize high in the tree. That silently shrinks every Material control below it. If you see that override, treat it as a bug unless there's a documented reason.

Also watch spacing: two 48dp targets that touch edge to edge are technically compliant and still easy to mis-tap. Leave at least 8dp between adjacent actions.

Rule 3: Text has enough contrast to read

The WCAG thresholds are the de facto standard: 4.5:1 for normal text, 3:1 for large text (WCAG defines this as 18pt regular or 14pt bold, which is roughly 24sp and 18.7sp on Android), and 3:1 for meaningful non-text UI like input borders and icons.

The most useful thing a senior engineer can do here is turn contrast into a test against your theme tokens instead of a one-off check in a design tool. The math lives in ui-graphics already:

/** WCAG 2.x contrast ratio. Translucent foregrounds are flattened onto the background first. */
fun contrastRatio(foreground: Color, background: Color): Float {
    val fg = foreground.compositeOver(background).luminance()
    val bg = background.luminance()
    val lighter = maxOf(fg, bg)
    val darker = minOf(fg, bg)
    return (lighter + 0.05f) / (darker + 0.05f)
}

import kotlin.test.Test
import kotlin.test.assertTrue

class ThemeContrastTest {

    private fun ColorScheme.textPairs() = mapOf(
        "onSurface/surface" to (onSurface to surface),
        "onSurfaceVariant/surface" to (onSurfaceVariant to surface),
        "onPrimary/primary" to (onPrimary to primary),
        "error/surface" to (error to surface),
        "secondaryText/surface" to (onSurface.copy(alpha = 0.7f) to surface),
    )

    @Test
    fun textRolesMeetWcagAa() {
        val failures = mapOf("light" to AppLightColors, "dark" to AppDarkColors)
            .flatMap { (themeName, scheme) ->
                scheme.textPairs().mapNotNull { (role, pair) ->
                    val ratio = contrastRatio(pair.first, pair.second)
                    if (ratio < 4.5f) "$themeName/$role = ${"%.2f".format(ratio)}:1" else null
                }
            }
        assertTrue(failures.isEmpty(), "Contrast failures:\n${failures.joinToString("\n")}")
    }
}

Note the compositeOver call. The most common real-world contrast regression isn't a bad palette; it's color.copy(alpha = 0.6f) used for "secondary" text. On a light surface it may scrape by. On a dark surface, the same alpha can drop well below 4.5:1. Measuring the raw color without compositing hides the problem completely.

Dark theme pitfalls, briefly:

• Brand colors tuned for white backgrounds often fail on dark surfaces. Give dark theme its own tonal values rather than reusing the light ones.
• Elevated surfaces in Material 3 dark theme are lighter than the base surface. Text that passes on surface may fail on surfaceContainerHighest, so test the containers you actually use.
• Disabled controls are exempt from WCAG contrast, but disabled is not the same as “secondary.” Don’t use disabled styling for content users need to read.

For quick manual checks, Google’s Accessibility Scanner flags low-contrast text on a running screen, and Part 3 of this series automates the same check in instrumented tests.

Rule 4: Never let color carry meaning alone

If you convert your screen to grayscale and something stops making sense, you’re relying on color alone. Error states are the classic case: a red border that means “this field is invalid” is invisible to many color-blind users and meaningless to TalkBack.

Redundancy is the fix: color plus an icon plus text on screen, and a single, specific error for assistive tech.

<string name="error_with_prefix">Error: %1$s</string>

@Composable
fun EmailField(
    value: String,
    onValueChange: (String) -> Unit,
    errorMessage: String?,
    modifier: Modifier = Modifier,
) {
    OutlinedTextField(
        value = value,
        onValueChange = onValueChange,
        label = { Text(stringResource(R.string.label_email)) },
        isError = errorMessage != null,
        trailingIcon = errorMessage?.let {
            { Icon(Icons.Filled.Error, contentDescription = null) } // the text explains it
        },
        supportingText = errorMessage?.let { message ->
            {
                Text(
                    text = stringResource(R.string.error_with_prefix, message),
                    // Visual only: the reason reaches TalkBack once, via error() below.
                    modifier = Modifier.clearAndSetSemantics { },
                )
            }
        },
        singleLine = true,
        modifier = modifier.semantics {
            // With isError = true, Material 3 attaches a generic, localized error
            // description ("Invalid input" in English). Replace it with the real reason.
            if (errorMessage != null) error(errorMessage)
        },
    )
}

Why clear the supporting text’s semantics? The field merges its decorations into one node, so if both the supporting text and error() carry the message, TalkBack reads it twice in a row. Pick one channel for speech. The error() property is the better one: TalkBack announces it as an error, and Part 3's tests can assert on it directly. Behavior varies across Material 3 and TalkBack versions, so confirm on a device that you hear the message exactly once.

The same principle applies well beyond forms:

• Status chips (“Shipped,” “Delayed,” “Cancelled”) need a text label, not just a green, amber, or red dot.
• Charts need direct labels or patterns, not a legend that maps five similar hues.
• Required fields need an asterisk and a “required” label in semantics, not only a colored label.
• Links in body text need an underline or weight change, not just a different color.

Rule 5: The reading order matches the visual intent

TalkBack users move through a screen element by element with swipes. Compose builds that order from the semantics tree and then sorts siblings geometrically: roughly top to bottom, then start to end, grouping elements that share a row. For simple Column and Row layouts, that's exactly what you want.

It goes wrong when your layout is organized in columns that should be read one at a time. A side-by-side plan comparison is the textbook case:

Out of the box, TalkBack reads row by row across both columns: “Basic, Pro, ₹149 a month, ₹399 a month…” The user hears two products shuffled together. The fix is to tell Compose each column is a unit:

@Composable
fun PlanComparison(basic: Plan, pro: Plan, modifier: Modifier = Modifier) {
    Row(
        modifier = modifier,
        horizontalArrangement = Arrangement.spacedBy(16.dp),
    ) {
        PlanColumn(basic, Modifier.weight(1f).semantics { isTraversalGroup = true })
        PlanColumn(pro, Modifier.weight(1f).semantics { isTraversalGroup = true })
    }
}

For finer control within a group, traversalIndex reorders siblings (lower values come first; the default is 0f). A common case is an overlay action pinned to the top corner of a card. Geometry says read it first; intent says read the content first:

@Composable
fun DealCard(deal: Deal, onSave: () -> Unit) {
    Box(Modifier.semantics { isTraversalGroup = true }) {
        Image(
            painter = painterResource(deal.imageRes),
            contentDescription = null,
            contentScale = ContentScale.Crop,
            modifier = Modifier.fillMaxWidth().aspectRatio(16f / 9f),
        )
        IconButton(
            onClick = onSave,
            modifier = Modifier
                .align(Alignment.TopEnd)
                .semantics { traversalIndex = 1f }, // after title and price
        ) {
            Icon(
                Icons.Outlined.FavoriteBorder,
                contentDescription = stringResource(R.string.cd_save_deal, deal.title),
            )
        }
        Column(Modifier.align(Alignment.BottomStart).padding(16.dp)) {
            Text(deal.title, style = MaterialTheme.typography.titleMedium)
            Text(deal.priceLabel)
        }
    }
}

When not to override. Traversal overrides are a patch, not a design tool. If you find yourself setting traversalIndex on half a screen, the layout structure itself is probably wrong, and restructuring will fix TalkBack, keyboard navigation, and future maintainers all at once. Overrides also don't survive refactors well: a stray index left behind after someone moves a composable creates order bugs nobody can explain.

A five-minute exercise

Do this today, on your own app:

1. Enable TalkBack (Settings → Accessibility → TalkBack), or toggle it with the volume-key shortcut.
2. In TalkBack’s developer settings, turn on Display speech output so you can read what it says.
3. Open your busiest screen and swipe right through every element without looking at the layout.
4. Write down every “Unlabeled,” every duplicated phrase, and every moment you lose track of where you are.

Most teams find at least one issue per screen the first time they do this. That list is your backlog.

Common mistakes

• Repeating the role in the label. Setting contentDescription = "Submit button" on a Button that already shows "Submit" produces "Submit button, Submit, Button." TalkBack announces the role itself.
• Describing decoration. Labelling dividers, background shapes, and avatar placeholders forces users to swipe past noise on every visit.
• Trusting Material to cover everything. Stock components handle roles, states, and touch size, but they can’t invent a meaningful label for your icon, fix your theme’s contrast, or know that your columns should be read separately.

The baseline checklist

Print this, pin it next to your PR template, or turn each line into a review question.

Up next

These five rules cover screens built from standard components. But the moment you build your own, like a star rating, a custom slider, or a swipe carousel, TalkBack sees a pile of unrelated shapes. Part 2, Making Custom Composables Speak, walks through the Compose semantics tree and turns a five-icon rating widget into a single, operable control.

📱 Go Beyond Using Jetpack Compose

If you’re building on Android, understanding what happens under the hood separates developers who use Compose from those who master it. I highly recommend “Mastering Jetpack Compose Internals”. It’s a deep, architecture-first walkthrough of the composition tree, the slot table, snapshot state, and the runtime that powers modern Android UI — capped off with a full case study building a real app called Mosaic.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover

Originally published on Medium.

• remember forgets everything on a configuration change.
• rememberSaveable demands something a Bundle can carry.
• A ViewModel works, but for a single screen-scoped helper it is a lot of ceremony.

retain fills that gap. It shipped stable in Compose 1.10 (BOM 2025.12.00), and this post covers what it does, where it fits, and the failure modes you will hit in production. (APIs this young move, so check signatures against the current release notes before copying code verbatim.)

The mental model

remember stores a value in the composition. When the Activity is recreated, the composition is thrown away and the value goes with it.

rememberSaveable stores a serialized copy in saved instance state. The value is rebuilt from that copy, so it must be Bundle-friendly and small, since the Bundle is shared with a size-limited cross-process transaction.

retain does neither. It keeps the actual instance alive in memory while the Activity is torn down and rebuilt, then hands the same instance back to the new composition. Nothing is serialized, so there is no type restriction and no Bundle budget.

Two API facts to know up front. retain lives in the androidx.compose.runtime.retain package of Compose Runtime 1.10+. And it retains only as far as the surrounding RetainedValuesStore allows: the default store is forgetful, which makes retain behave exactly like remember. Compose UI's Android host supplies a store that survives Activity recreation, but if you build custom hosts or tests, check which store is in play. Also, retaining an object that implements RememberObserver without also implementing RetainObserver throws, and you can mark a class with @DoNotRetain to forbid retaining it.

The trade-off is in the last column of that card: retained values live on the process heap. They have no answer for process death.

A first example

Here is a search screen that owns a small pipeline: a query flow, a debounce, and a result stream. Rebuilding it on rotation would cancel in-flight requests and flash the UI.

import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.retain.RetainObserver
import androidx.compose.runtime.retain.retain
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import kotlinx.coroutines.*
import kotlinx.coroutines.flow.*

@OptIn(FlowPreview::class, ExperimentalCoroutinesApi::class)
class CatalogSearch(private val api: CatalogApi) : RetainObserver {

    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
    private val queries = MutableStateFlow("")

    val results: StateFlow<List<Item>> = queries
        .debounce(250)
        .distinctUntilChanged()
        .mapLatest { q -> if (q.isBlank()) emptyList() else api.search(q) }
        .stateIn(scope, SharingStarted.WhileSubscribed(5_000), emptyList())

    fun onQueryChanged(q: String) { queries.value = q }

    override fun onRetained() = Unit
    override fun onEnteredComposition() = Unit
    override fun onExitedComposition() = Unit
    override fun onUnused() = scope.cancel()   // created but never applied
    override fun onRetired() = scope.cancel()  // screen is gone for good
}

@Composable
fun CatalogScreen(api: CatalogApi) {
    val search = retain(api) { CatalogSearch(api) }
    val results by search.results.collectAsStateWithLifecycle()

    SearchField(onChange = search::onQueryChanged)
    ResultList(results)
}

Three details matter here. The api key rebuilds the object if the dependency changes. Collection uses collectAsStateWithLifecycle() (from lifecycle-runtime-compose) so it pauses in the background. And the class implements RetainObserver, so its scope is cancelled when the value is retired rather than leaking until process death.

Rotate the device mid-typing: the same CatalogSearch instance, same scope, same debounce window. No Parcelable, no ViewModelProvider.

Retained state that drives recomposition

retain stores whatever you hand it. If you want a value that is both retained and observable, retain a MutableState:

@Composable
fun TapCounter() {
    val count = retain { mutableIntStateOf(0) }

    Button(onClick = { count.intValue++ }) {
        Text("Taps: ${count.intValue}")
    }
}

mutableIntStateOf avoids boxing for a primitive counter, and the retained state holder is the same instance after rotation. Writes to it still trigger recomposition exactly as they would with remember.

Choosing between the options

A rule of thumb that has held up well: if losing the value on a rotation would hurt, but losing it after process death is acceptable, retain is a candidate. If the value must also survive process death, you need rememberSaveable or a ViewModel backed by SavedStateHandle.

retain is also screen-level by design. Per-item state inside LazyColumn items is a poor fit, because items enter and leave composition constantly while scrolling. Hoist that state into a ViewModel, or use rememberSaveable keyed by a stable item ID.

Teardown: the part people forget

A retained object outlives the composition that created it. That is the point, and also the hazard. Something has to release it when the screen is actually done, not merely rotated.

Compose provides RetainObserver for this. An object is retained when retain first returns it, may enter and exit composition any number of times (rotation is exactly that), and is retired once it is removed from composition and no store is keeping it. The interface has five callbacks: onRetained, onEnteredComposition, onExitedComposition, onRetired, and onUnused, which fires when the value was created but the composition was abandoned before applying it. The opening example already shows the pattern; cancel in both onRetired and onUnused.

For one-off side effects that don’t belong inside a class, RetainedEffect gives you a DisposableEffect-style block whose cleanup runs on retirement rather than on every rotation.

Tie cancellation to retirement, never to onDispose of a DisposableEffect. onDispose fires on every rotation, which would cancel the very scope you just worked to preserve.

Four failure modes from production

1. The leaked Activity

The classic. A retained object captures a Context obtained from LocalContext.current, which is the Activity. After rotation the old Activity cannot be collected, because your retained object still points at it.

// Leaks the Activity across every rotation
val player = retain { VideoSession(LocalContext.current) }

// Safer: pass only what the object genuinely needs
val appContext = LocalContext.current.applicationContext
val player = retain { VideoSession(appContext) }

Better still, inject the collaborators an object needs (an ExoPlayerFactory, a repository) instead of any Context. Audit every constructor argument of a retained object for UI references: views, Activities, Resources tied to a themed context, listeners that close over composables.

2. Nothing ever shuts it down

Retained coroutine scopes keep collecting. Retained players keep their codecs. Retained socket wrappers keep sockets. If the screen is dismissed and nothing cancels the work, it runs until the process dies. Use onRetired/onUnused as shown above, and verify it with a leak-canary style test that pops the screen and asserts the scope is cancelled.

3. Assuming it survives process death

Retained values are plain heap objects. When the system reclaims your process in the background, they are gone, and the restored screen starts from scratch. Anything the user would be upset to lose, a draft, a selected ID, a scroll anchor, must also go through rememberSaveable or SavedStateHandle.

A pattern that works well is to save the identity and retain the machinery:

class ArticleLoader(private val repo: ArticleRepository) : RetainObserver {
    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
    private var loadedId: String? = null
    val state = MutableStateFlow<ArticleUiState>(ArticleUiState.Idle)

    fun load(id: String) {
        if (id == loadedId) return        // idempotent: a rotation must not reload
        loadedId = id
        scope.launch { state.value = ArticleUiState.Ready(repo.fetch(id)) }
    }

    override fun onRetained() = Unit
    override fun onEnteredComposition() = Unit
    override fun onExitedComposition() = Unit
    override fun onUnused() = scope.cancel()
    override fun onRetired() = scope.cancel()
}

@Composable
fun ArticleScreen(repo: ArticleRepository) {
    var articleId by rememberSaveable { mutableStateOf<String?>(null) }
    val loader = retain(repo) { ArticleLoader(repo) }
    val ui by loader.state.collectAsStateWithLifecycle()

    LaunchedEffect(articleId) { articleId?.let(loader::load) }
    // render ui ...
}

LaunchedEffect re-runs after every recreation, so the retained loader makes load idempotent. After a rotation it is a no-op; after process death the loader is new, loadedId is null, and the saved ID triggers a fresh load.

4. Stale inputs

A retained lambda runs once. If the object was built from a parameter that later changes, it keeps using the old one. Pass the changing inputs as keys so the value is rebuilt when they change:

val search = retain(api, userId) { CatalogSearch(api, userId) }

When the keys change, the previous instance is retired (and your teardown runs) before the new one takes over. That is exactly why teardown belongs in the retirement callback.

Testing notes

Retained values tie directly to Activity recreation, so unit tests on composables will not catch most of these bugs. Use an instrumented test that calls ActivityScenario.recreate() and asserts two things: the object identity is unchanged after recreation, and the teardown fires only after the screen is removed. Also run your leak detector across a rotation; a leaked Activity from failure mode one shows up immediately.

When I would still reach for a ViewModel

• The state must survive process death through SavedStateHandle.
• Several screens or destinations share the same object.
• Your team already has conventions, tooling, and test fixtures built around ViewModel.
• The object participates in per-item logic inside lazy layouts.

retain is not a ViewModel replacement. It is a smaller tool for a narrower, very common job: one screen, one heavy helper, rotation-safe, no ceremony. Compose-first architectures such as Circuit, where presenters are themselves composable, are a natural home for it.

🔚 Takeaways

1. retain keeps the real instance alive across configuration changes, with no serialization and no Bundle limit.
2. It retains only as far as the host’s RetainedValuesStore allows, and it does not survive process death. Save identity with rememberSaveable, retain machinery.
3. Wrap mutableStateOf (or its primitive variants) inside retain when you need retained state that drives recomposition.
4. Never capture an Activity-scoped Context in a retained object.
5. Release resources on retirement, not on onDispose.
6. Keep it screen-level; hoist per-item state out of lazy layouts.

Are you already using retain in a real project? I would like to hear which failure mode bit you first.

📱 New to Jetpack Compose? Start Here

If you’re coming from the classic Android View system — XML layouts, findViewById, RecyclerView adapters — and want a clear, no-jargon path into Jetpack Compose, I recommend "Learning Jetpack Compose: Your Practical Guide from the Android View System to Modern Declarative UI." Every chapter starts from something you already know and shows its Compose equivalent side by side, building up to a full capstone: a real Notes app. Once you're comfortable and want to go deeper — the Composition tree, recomposition internals, the runtime itself — "Mastering Jetpack Compose Internals" is the natural next step.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover

Originally published on Medium.

Then a Room query returns zero rows, a Flow emits its first empty list, and a screen crashes in production with UnsupportedOperationException. Or a "harmless" reduce quietly rewrites the first item in your UI state. Or a total of cached bytes wraps around to a negative number on a device with a big cache.

All of these trace back to one question: where does the accumulator start?

This post walks through the mechanics, the type rules that follow from them, and the failure modes I would flag in a code review. The examples use a download and sync domain, so none of it is tied to a particular app.

The one difference that matters

• fold(initial) starts from a value you provide, then processes every element.
• reduce starts from the first element and processes the remaining ones.

Here is the same sum written both ways:

data class DownloadPart(
    val index: Int,
    val bytes: Long,
    val error: String? = null,
)

val parts = listOf(
    DownloadPart(index = 0, bytes = 4_096),
    DownloadPart(index = 1, bytes = 8_192),
    DownloadPart(index = 2, bytes = 2_048),
)

// reduce needs elements that are already the accumulator's type, so we map first.
val viaReduce: Long = parts
    .map { it.bytes }
    .reduce { acc, bytes -> acc + bytes }

// fold starts from 0L, so it can read the field directly and skips the intermediate list.
val viaFold: Long = parts.fold(0L) { acc, part -> acc + part.bytes }

Both give 14_336. Look at what each version had to do to get there, though. The reduce version had to turn DownloadPart into Long first, because the accumulator and the elements share a type. The fold version was free to bring its own seed type.

(For a plain sum you would normally write parts.sumOf { it.bytes }. I'm using fold here because it is the simplest case that shows the mechanics.)

Type freedom: why fold builds state and reduce merges values

Because fold takes an explicit seed, its result type R is independent of the element type T:

inline fun <T, R> Iterable<T>.fold(
    initial: R,
    operation: (acc: R, T) -> R,
): R

reduce has no seed to infer anything from. Its signature ties the accumulator to the elements:

inline fun <S, T : S> Iterable<T>.reduce(
    operation: (acc: S, T) -> S,
): S

S has to be a supertype of T, so in practice the result is the element type, or a common parent of it.

That is why fold is the natural tool when you are building a different shape out of a list. Here a list of parts becomes a transfer report:

data class TransferReport(
    val completedBytes: Long = 0,
    val failedParts: List<Int> = emptyList(),
)

fun List<DownloadPart>.toReport(): TransferReport =
    fold(TransferReport()) { report, part ->
        if (part.error == null) {
            report.copy(completedBytes = report.completedBytes + part.bytes)
        } else {
            report.copy(failedParts = report.failedParts + part.index)
        }
    }

reduce could not express this, since DownloadPart and TransferReport have nothing in common.

reduce is the better fit when the first element really is a valid starting point and you are merging same-shaped values. A good example is combining time windows into one covering window:

data class SyncWindow(val startMs: Long, val endMs: Long)

fun List<SyncWindow>.coveringWindow(): SyncWindow? =
    reduceOrNull { a, b ->
        SyncWindow(
            startMs = minOf(a.startMs, b.startMs),
            endMs = maxOf(a.endMs, b.endMs),
        )
    }

There is no meaningful “zero window” to seed with, which is exactly why starting from the first element feels natural here. The function returns SyncWindow? for a reason, and the next section explains it.

Failure mode 1: the empty collection

reduce cannot produce a value when there is no first element, so it throws. fold already holds its seed, so it simply returns it.

On Android, empty collections are normal runtime states. They show up on a fresh install, after “clear cache”, on the first emission of a Flow, and for an account with no data yet. Here is a bug I have seen in different forms in several codebases:

class StorageViewModel(dao: CachedFileDao) : ViewModel() {

    val usedBytes: StateFlow<Long> = dao.observeAll()
        .map { files ->
            files.map { it.sizeBytes }.reduce { a, b -> a + b } // throws when the cache is empty
        }
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), 0L)
}

It works in every manual test, because the tester always has data. It crashes the first time observeAll() emits an empty list. A crash inside map on a flow collected by stateIn goes through the scope's exception handling, so depending on your setup it can take down the screen or the whole process.

You have three sound fixes, and the choice depends on what “empty” should mean:

// 1. An empty total is a legitimate zero.
files.fold(0L) { acc, f -> acc + f.sizeBytes }   // or simply files.sumOf { it.sizeBytes }

// 2. Absence is a legitimate answer and the caller must handle it.
files.map { it.lastAccessMs }.reduceOrNull { a, b -> maxOf(a, b) }   // Long?

// 3. The input is guaranteed non-empty, and you document why.
require(files.isNotEmpty()) { "Cache snapshot must contain at least one entry" }

My rule is that reduce is acceptable only when I can point to the line that guarantees non-emptiness. If I can't, it is fold or reduceOrNull.

Failure mode 2: reduce mutates your first element

Because the first element becomes the accumulator, a lambda that mutates acc mutates your data:

class ShardTally(var hits: Int, var misses: Int)

val combined = shardTallies.reduce { acc, t ->
    acc.also {
        it.hits += t.hits
        it.misses += t.misses
    }
}

After this call, shardTallies[0] holds the combined totals. If that list backs a StateFlow, observers now hold an object that changed without any emission. Call the function a second time and the first shard is counted twice. This kind of bug is slow to reproduce, because it depends on call order.

The fix is to produce new values and keep the elements immutable:

data class ShardTally(val hits: Int = 0, val misses: Int = 0)

val combined = shardTallies.fold(ShardTally()) { acc, t ->
    ShardTally(acc.hits + t.hits, acc.misses + t.misses)
}

Failure mode 3: the shared mutable seed

fold has a mirror-image trap. The seed is just an argument, so if you hand it something that outlives the call, every call mutates the same object:

private val pending = mutableListOf<String>()   // lives as long as the class

fun collectNames(parts: List<DownloadPart>): List<String> =
    parts.fold(pending) { acc, p -> acc.apply { add("part-${p.index}") } }

The first call returns three names. The second returns six. Always construct the seed inside the call, for example fold(mutableListOf<String>()).

Failure mode 4: the O(n²) copy-on-every-step

Immutable seeds and copy() read nicely, but + on a List or Map allocates a new collection each time. In the earlier toReport() I used report.failedParts + part.index, which is fine for a handful of parts and quietly quadratic for a large journal.

For large inputs, accumulate into a private builder and freeze it once at the end:

fun List<DownloadPart>.toReportFast(): TransferReport {
    var completed = 0L
    val failed = ArrayList<Int>()
    for (part in this) {
        if (part.error == null) completed += part.bytes else failed += part.index
    }
    return TransferReport(completedBytes = completed, failedParts = failed)
}

This is still a fold in spirit, and the mutable state never escapes the function. If you prefer to keep the fold shape, seed it with a small private accumulator class and read it out at the end. Either way, measure first. Most lists on a phone screen are short enough that readability wins.

Failure mode 5: integer overflow in the seed

The seed’s type is chosen by you, and 0 is an Int:

// sizeKb is an Int field on each cache entry
val totalBytes = entries.fold(0) { acc, e -> acc + e.sizeKb * 1024 }

Once the cache passes 2 GiB, this wraps to a negative number. A “storage used” label that shows -1.9 GB is a good way to learn that fold(0) and fold(0L) are different programs. Pick the widest sensible type for the seed, and convert before multiplying (e.sizeKb.toLong() * 1024).

Failure mode 6: swapping one for the other changes the answer

Replacing reduce with fold(0) looks like a safe refactor. It is safe for addition, because the seed is the identity element. It silently changes results for operations where the first element is special:

val steps = listOf(100, 30, 20)

steps.reduce { a, b -> a - b }   // 50    (100 - 30 - 20)
steps.fold(0) { a, b -> a - b }  // -150  (0 - 100 - 30 - 20)

The same applies to min/max-style merges, string joins with separators, and anything non-commutative. Before swapping, ask whether your seed is a true identity for the operation.

Where fold really shines: replayable state

Android developers see the clearest payoff of fold in unidirectional state. A reducer has the shape (State, Event) -> State, which is exactly what fold expects, and reduce could never fit it because the two types differ.

sealed interface SyncEvent {
    data class Started(val totalParts: Int) : SyncEvent
    data class PartDone(val bytes: Long) : SyncEvent
    data class Failed(val reason: String) : SyncEvent
}

data class SyncState(
    val totalParts: Int = 0,
    val doneBytes: Long = 0,
    val failure: String? = null,
) {
    fun transition(event: SyncEvent): SyncState = when (event) {
        is SyncEvent.Started -> copy(totalParts = event.totalParts, doneBytes = 0, failure = null)
        is SyncEvent.PartDone -> copy(doneBytes = doneBytes + event.bytes)
        is SyncEvent.Failed -> copy(failure = event.reason)
    }
}

// Rebuild the state after process death from a persisted event journal.
val restored: SyncState = journal.fold(SyncState(), SyncState::transition)

// Same events, but keep every intermediate state, for debugging or time-travel tooling.
val timeline: List<SyncState> = journal.runningFold(SyncState(), SyncState::transition)

Two production notes:

• The reducer must be deterministic. No clock reads, no random IDs, no I/O inside transition. If replay produces a different state than the original run, the journal is useless.
• Version your events. A journal written by last month’s app will contain shapes that today’s when has never seen. Decide on purpose whether unknown events are skipped, migrated, or fatal.

If the journal can grow large, run the fold on Dispatchers.Default rather than the main thread, and use asSequence() first when you also filter or map to avoid intermediate lists.

A quick decision guide

In words, the questions I ask are:

1. Do I need to define the starting state myself? If yes, use fold.
2. Is the first element naturally the starting state, and is the result the same type as the elements? If yes, reduce can be the cleaner choice.
3. Can the collection be empty at runtime? If so, use fold with a sensible seed, or reduceOrNull and handle the null.

🔚 Takeaways

• The only real difference is the starting accumulator, but it drives everything else: type flexibility, empty-input behavior, and what your lambda is allowed to mutate.
• fold is the default for building state or a different type, and for any input that might be empty.
• reduce is for merging same-typed values when the first element is a valid start and non-emptiness is guaranteed, or when you use reduceOrNull and handle the null.
• Never mutate the accumulator when it is also one of your elements, and never reuse a seed across calls.
• Choose the seed’s numeric type deliberately, and check that the seed is an identity before swapping reduce for fold.

Once the accumulator is the first thing you look at, the two functions stop being confusing and start reading as two different statements about where your data begins.

📘 Master Your Next Technical Interview

Since Java is the foundation of Android development, mastering DSA is essential. I highly recommend “Mastering Data Structures & Algorithms in Java”. It’s a focused roadmap covering 100+ coding challenges to help you ace your technical rounds.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover.

Originally published on Medium.

Three different complaints, one root cause: the build-and-runtime pipeline is a black box to most of the team. This post opens it. We follow a single Kotlin line from ./gradlew assembleRelease through Gradle, AAPT2, R8, signing, Play delivery, and finally ART on the device, and at each stage we look at how it actually fails in production.

Every code sample uses a fictional app, Harborlane, a ferry-ticketing client. Package names are dev.harborlane.*.

The rest of the article walks that picture left to right, top to bottom.

1. Gradle: the planner that runs before anything compiles

The three phases

Gradle never “just builds”. It works in three distinct phases:

1. Initialization. Gradle reads settings.gradle.kts and decides which projects take part.
2. Configuration. Every participating project’s build script is evaluated, tasks are registered, and the task graph (a directed acyclic graph) is assembled.
3. Execution. Only the tasks required by the requested target run, and each one first asks, “Do I even need to?”

The key asymmetry: execution has long been cache-friendly (up-to-date checks, the build cache), while configuration historically was not. The configuration cache (stable since Gradle 8.1, opt in with org.gradle.configuration-cache=true) changes that by serializing the result of the configuration phase and skipping script evaluation entirely on a hit. But a hit requires unchanged inputs and plugins and scripts that are compatible with it, which is exactly where configuration-time work bites. On a miss, whatever your scripts do while being evaluated is paid for on every command, including ./gradlew help, IDE syncs, and CI shards.

Failure mode: the configuration-time tax

This is a real pattern that has quietly added minutes to builds:

// app/build.gradle.kts: evaluated on EVERY Gradle invocation
val gitSha: String = Runtime.getRuntime()
    .exec(arrayOf("git", "rev-parse", "--short", "HEAD"))
    .inputStream.bufferedReader().readText().trim()

android {
    defaultConfig {
        buildConfigField("String", "GIT_SHA", "\"$gitSha\"")
        // Worse: a value that is different on every run
        buildConfigField("long", "BUILT_AT", "${System.currentTimeMillis()}L")
    }
}

There are two separate sins here:

• The process spawn happens at configuration time, in every project that applies the script, even when you are only asking Gradle for its help text.
• BUILT_AT changes every run, so the generated BuildConfig is never up to date. Everything downstream (compilation, dexing, packaging) is invalidated, and the build cache can never produce a hit for it.

The fix is to model the value as a lazy provider and feed it to a task as a declared input:

// build-logic or app/build.gradle.kts
import org.gradle.api.DefaultTask
import org.gradle.api.file.DirectoryProperty
import org.gradle.api.provider.Property
import org.gradle.api.tasks.*

@CacheableTask
abstract class GenerateBuildInfo : DefaultTask() {

    @get:Input
    abstract val gitSha: Property<String>

    @get:OutputDirectory
    abstract val outputDir: DirectoryProperty

    @TaskAction
    fun generate() {
        val file = outputDir.get().asFile.resolve("dev/harborlane/BuildInfo.kt")
        file.parentFile.mkdirs()
        file.writeText(
            """
            package dev.harborlane

            internal object BuildInfo {
                const val GIT_SHA = "${gitSha.get()}"
            }
            """.trimIndent()
        )
    }
}

val gitShaProvider: Provider<String> = providers
    .exec { commandLine("git", "rev-parse", "--short", "HEAD") }
    .standardOutput.asText
    .map { it.trim() }

androidComponents.onVariants { variant ->
    val taskName = "generate${variant.name.replaceFirstChar(Char::uppercase)}BuildInfo"
    val generate = tasks.register<GenerateBuildInfo>(taskName) {
        gitSha.set(gitShaProvider)
    }
    variant.sources.java?.addGeneratedSourceDirectory(generate, GenerateBuildInfo::outputDir)
}

Three idioms matter here: tasks.register instead of create (the task is only configured if it is actually needed), Property/Provider instead of eager values, and annotated inputs and outputs so Gradle can fingerprint the task. providers.exec is the configuration-cache-compatible replacement for Project.exec: it returns a lazy provider, and the process only runs when something resolves that provider (here, when Gradle fingerprints the task's @Input). The resolved value is then recorded as a configuration cache input, so a new commit correctly invalidates the cache entry. If you ever need the value during configuration (for example for buildConfigField), wrap the command in a custom ValueSource so the cache can track it, and accept that this value is read at configuration time. One honest caveat: a commit hash as an input means the generated file changes on every commit. Keep it tiny and isolated in its own module so only a small slice recompiles.

Up-to-date checks, incremental builds, and the build cache

Three mechanisms often get lumped together; they are different:

• UP-TO-DATE: inputs and outputs of this task are unchanged in this working directory, so skip it.
• Incremental task: the task does run, but processes only the changed inputs (Kotlin compilation works this way).
• FROM-CACHE: a task with identical input fingerprints ran somewhere else (another branch, another CI agent), so its outputs are restored from the build cache.

Cache hits depend on fingerprints being deterministic and relocatable. The usual saboteurs are absolute paths baked into inputs, timestamps, random UUIDs, and un-normalized line endings. If your remote cache hit rate is poor, run a build twice on different checkouts with -Dorg.gradle.caching.debug=true, or compare Build Scans, to see which input fingerprint differs.

Build variants

Build types and product flavors form a matrix. Each cell is a complete, buildable variant with its own tasks and its own source set.

android {
    namespace = "dev.harborlane.app"
    compileSdk = 36

    defaultConfig { minSdk = 23 }

    flavorDimensions += "env"
    productFlavors {
        create("dev") {
            dimension = "env"
            applicationIdSuffix = ".dev"
            resValue("string", "app_name", "Harborlane Dev")
        }
        create("prod") { dimension = "env" }
    }

    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }
}

When the same file exists in several source sets, the most specific one wins: src/devDebug beats src/debug or src/dev, which beat src/main. That is a feature (swap an API endpoint per environment) and a trap (a stray file in src/dev silently shadows production behavior in only one variant).

Debugging a slow build, in order

1. ./gradlew assembleRelease --dry-run shows which tasks would run and in what order, without running them.
2. ./gradlew assembleRelease --scan gives a timeline and a per-task cache verdict.
3. Android Studio’s Build Analyzer points at plugins and tasks that always rerun.
4. Compare configuration time against execution time first. If help itself is slow, the problem is in your scripts, not your compiler.

2. Resources and manifests: two merges before a single class compiles

AAPT2 in two steps

AAPT2 is split into compile and link so that it can be incremental:

• Compile converts each resource file into an intermediate .flat unit. Edit one layout and only that unit is redone.
• Link takes all .flat files plus the merged manifest and produces the final resources.arsc, the resource-ID table, and the generated R class (for AAB, a protobuf-format variant).

A resource ID is a 32-bit integer in the form 0xPPTTEEEE: package (0x7f for your app), resource type, and entry. IDs are assigned at link time, which is why they must never be persisted or hard-coded, and why library modules cannot treat their R fields as true constants.

Failure mode: the resource shrinker and names it cannot see

isShrinkResources = true removes resources that nothing references. By default the shrinker runs in a forgiving safe mode: if it finds string constants that look like the prefix of a resource name (for example "banner_" passed to getIdentifier), it conservatively keeps every resource matching that pattern. That heuristic is why many apps never notice the problem, and also why the failure below shows up only when the pattern is invisible:

// routeAsset arrives from remote config, e.g. "banner_summer_sale"
fun bannerFor(context: Context, routeAsset: String): Int =
    context.resources.getIdentifier(routeAsset, "drawable", context.packageName)

The full name is built outside the app, so the dex contains no recognizable constant prefix and the shrinker has nothing to match. Banners vanish in release only, and getIdentifier returns 0. The same happens if you opt into tools:shrinkMode="strict", which disables the heuristics on purpose. Declare the dynamic family explicitly:

<!-- res/raw/keep.xml -->
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@drawable/banner_*" />

Better still, map the allowed values through an explicit when over real R.drawable references; the compiler and the shrinker then both see the dependency, and an unknown value becomes a handled case instead of a silent 0.

Manifest merging and conflict resolution

The merger combines the manifests of your build variant, your main source set, and every library, with priority in that order. When two sources disagree on the same attribute and the higher-priority one does not say it wins, the build fails with a “Manifest merger failed” error. Resolve it deliberately, using the tools namespace:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- A transitive analytics SDK declares this; we don't want it -->
    <uses-permission
        android:name="android.permission.READ_PHONE_STATE"
        tools:node="remove" />

    <application
        android:allowBackup="false"
        android:label="@string/app_name"
        tools:replace="android:allowBackup,android:label" />
</manifest>

Use tools:replace for individual attributes and tools:node="remove" or "replace" for whole elements. Treat every marker as documentation of a decision, and check the Merged Manifest tab in Studio after adding a dependency, because a library can silently contribute permissions, exported components, or usesCleartextTraffic.

3. Compilation, desugaring, and shrinking: D8 versus R8

The path from text to dex

Kotlin and Java sources are compiled by kotlinc and javac into JVM .class files. Android does not run those. A dex tool translates them into register-based DEX bytecode for the runtime:

• D8 is the dexer. It converts classes to .dex and also desugars newer language constructs for older API levels.
• R8 is a superset used on minified builds. It does whole-program shrinking (removes unreachable code), optimization (inlining, merging, devirtualization), and obfuscation (renaming), and performs the dexing and desugaring itself.

Failure mode: modern java.time on an older device

Desugaring covers language features cheaply, but library APIs need the runtime to contain them. Code that compiles against java.time can still crash on API 23 unless you opt into library desugaring:

android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
}

Without it, the symptom is NoClassDefFoundError or NoSuchMethodError on specific API levels, and nothing in your emulator on API 35 will ever reproduce it. Keep one low-API device or emulator in your release checklist.

Failure mode: R8 removes or renames something you reach by name

R8 can only reason about what code references statically. Reflection, string-based class lookup, JNI, and serialization frameworks reach code in ways it cannot see. Here is a plugin loader driven by remote config:

interface CheckoutPlugin {
    val id: String
    fun launch(context: Context)
}

object PluginLoader {
    // className arrives from remote config, e.g. "dev.harborlane.pay.SepaPlugin"
    fun load(className: String): Result<CheckoutPlugin> = runCatching {
        val plugin = Class.forName(className)
            .getDeclaredConstructor()
            .newInstance()
        plugin as? CheckoutPlugin
            ?: error("$className does not implement CheckoutPlugin")
    }
}

In the debug build this works. In release, no call site mentions SepaPlugin, so R8 either drops it or renames it, and the lookup fails with ClassNotFoundException (or NoSuchMethodException if the class survived without its constructor). Returning a Result keeps that failure observable and recoverable instead of crashing checkout.

The fix is a rule that describes the relationship, not one class, so new plugins are covered automatically:

# proguard-rules.pro
-keep class * implements dev.harborlane.checkout.CheckoutPlugin {
    <init>();
}

Note the explicit <init>(). Since AGP 8, R8's full mode is the default, and in full mode R8 no longer assumes a default constructor must be kept just because a class is kept. Rules written against older behavior can break after an upgrade.

The same logic applies to JSON models parsed by reflection:

data class OrderDto(
    val orderId: String,
    val totalMinor: Long,
    val lines: List<LineDto>,
)

If Gson maps by field name and R8 renames orderId to a, the JSON key no longer matches. The result is not a crash at the parse site but a silent null or 0, which is worse:

-keepattributes Signature, *Annotation*
-keepclassmembers class dev.harborlane.data.remote.dto.** { <fields>; }

A senior-level observation: reaching for more keep rules is the second-best fix. Prefer libraries whose generated code is statically visible (Moshi codegen, kotlinx.serialization, Retrofit with a converter that does not need reflection on your models), because then R8 can do its job without your help and shrinks more of your app. Also, check whether a library ships its own consumer rules; if you author a library, publish them with consumerProguardFiles.

A repeatable R8 triage routine

1. Reproduce on a minified build. Add a staging build type that sets isMinifyEnabled = true and signs with the debug key, and run your instrumented tests against it in CI.
2. De-obfuscate the stack trace with the mapping.txt produced by that exact build: retrace mapping.txt crash.txt. Upload the mapping file to Play Console or your crash tool for every release.
3. Ask R8 why something exists with -whyareyoukeeping class dev.harborlane.pay.SepaPlugin, and inspect -printusage and -printseeds output to see what was removed and what your rules matched.
4. Fix the rule at the narrowest scope that survives refactoring, and add a test that loads the class by name.

4. Packaging, signing, and distribution

APK versus AAB

An APK is an installable artifact. An Android App Bundle is a publishing format: you upload it, and Google Play generates APKs tailored per device from it: a base APK plus configuration splits for screen density, CPU ABI, and language.

The practical outcomes are smaller downloads and the ability to ship optional dynamic feature modules later.

Failure mode: the in-app language switcher that does nothing

Because language splits are delivered only for the device’s configured languages, an app that lets users pick a language inside the app may find the strings for the chosen language were never installed. Either rely on the platform per-app language support or opt out of language splitting:

android {
    bundle {
        language { enableSplit = false }
    }
}

Signature schemes, V1 through V4

Practical consequences:

• AGP signs with V1 only when minSdk is below 24, and always with the newer schemes for the device generation they support.
• V4 is stored in a separate .idsig file and exists for incremental installation workflows.
• With Play App Signing, you sign uploads with an upload key and Google re-signs the delivered APKs with the app signing key. Losing the upload key is recoverable. Losing a self-managed signing key without rotation is not.

zipalign and ordering

zipalign aligns uncompressed entries inside the archive so they can be memory-mapped efficiently. Because V2 and later sign the archive as a whole, the sequence is align first, sign second. If you script packaging manually and reverse the order, signature verification fails. AGP does it correctly for you, which is one more reason to avoid hand-rolled packaging.

5. ART: what happens after install

From Dalvik to a hybrid runtime

Early Android used Dalvik with a JIT. Android 5.0 made ART the runtime and compiled everything ahead of time during install, which gave fast execution but slow installs and system updates and noticeable storage cost. From Android 7.0, ART became a hybrid:

1. The app starts in the interpreter, so install is quick.
2. Hot methods are JIT-compiled and the runtime records a profile of what was hot.
3. When the device is idle and charging, a background job (dex2oat) AOT-compiles the profiled methods.
4. Subsequent launches execute native code for exactly the code that mattered.

The weakness is obvious: the first launches, which are the ones that shape a user’s first impression and your retention numbers, happen before any profile exists.

Baseline Profiles close the cold gap

A Baseline Profile is a list of classes and methods, shipped inside your APK or bundle, that tells ART which code is critical for startup and common journeys. At install time ART can compile those entries ahead of time, so the very first launch already runs the hot path as native code.

Google’s documentation cites improvements on the order of 30 percent in code execution speed from first launch; treat that as a ceiling-style claim and measure your own app, because the gain depends on how much of your startup path is interpreted code.

Generating the profile is a Macrobenchmark-style test that exercises your critical user journeys. (includeInStartupProfile needs a reasonably recent benchmark-macro-junit4, 1.2 or later. Run the generator against the non-minified release-like variant the Baseline Profile plugin creates, so view IDs and class names are intact. Note the explicit checkNotNull: without it a missing view fails silently and you ship a profile that never saw your real screen.)

@RunWith(AndroidJUnit4::class)
class StartupProfileGenerator {

    @get:Rule
    val rule = BaselineProfileRule()

    @Test
    fun generate() = rule.collect(
        packageName = "dev.harborlane.app",
        includeInStartupProfile = true,
    ) {
        pressHome()
        startActivityAndWait()

        // Exercise the first real screen, not just the splash
        val list = device.wait(
            Until.findObject(By.res(packageName, "departures_list")), 5_000
        )
        checkNotNull(list) { "departures_list never appeared; the profile would miss the real startup path" }
        list.fling(Direction.DOWN)
    }
}

And you verify the benefit with a benchmark that compares compilation modes:

@RunWith(AndroidJUnit4::class)
class ColdStartBenchmark {

    @get:Rule
    val rule = MacrobenchmarkRule()

    @Test fun noCompilation() = coldStart(CompilationMode.None())

    @Test fun withProfile() =
        coldStart(CompilationMode.Partial(BaselineProfileMode.Require))

    private fun coldStart(mode: CompilationMode) = rule.measureRepeated(
        packageName = "dev.harborlane.app",
        metrics = listOf(StartupTimingMetric()),
        iterations = 10,
        startupMode = StartupMode.COLD,
        compilationMode = mode,
    ) {
        pressHome()
        startActivityAndWait()
    }
}

Failure modes worth knowing

• A profile that covers the splash screen only. Your journeys decide the value of the profile. Cover the first screen users really see, scrolling, and one or two common navigations.
• Benchmarking a debuggable build or an emulator. Numbers from either are misleading. Use a release-like, non-debuggable variant on a real device.
• Stale profiles after big refactors. Entries match class and method identities, so major renames or module moves reduce coverage; regenerate as part of releases, through the Baseline Profile Gradle plugin, rather than committing a file once and forgetting it.
• Sideloaded builds. Outside Play, the profileinstaller library is what lets the profile be installed from the APK; keep that dependency in.

6. The interview answers, in plain language

“What happens between./gradlew assembleRelease and the final artifact?" Gradle initializes the build, configures all projects, and constructs the task graph. Then tasks run in dependency order: resources are compiled and manifests merged, AAPT2 links resources and assigns IDs, Kotlin and Java compile to .class files, R8 shrinks, optimizes, obfuscates, and dexes them, the packaging task zips everything, aligns it, and signs it. Each task is skipped when up to date or restored from cache when its inputs match a previous run. For Play delivery, bundleRelease produces an AAB instead, which Play turns into per-device APKs.

“Why did R8 remove an essential class or method?” R8 keeps only what is reachable by static analysis from entry points such as manifest components and your keep rules. If the class is reached only through reflection, a string, JNI, or a serializer, it looks unreachable, so it is deleted or renamed. A keep rule declares the dynamic entry point to R8: -keep for classes and members that must survive intact, -keepclassmembers when members matter only if the class survives, and -keepnames when only the name is the problem. The better long-term answer is to remove the reflection.

“How do Baseline Profiles improve startup?” ART normally learns what is hot only after the app has run for a while. A Baseline Profile ships that knowledge with the app, so critical classes and methods can be compiled ahead of time at install, and the first launches skip most interpretation and JIT warm-up.

A pre-release checklist you can steal

• Run help and a no-op build; if either is slow, hunt configuration-time work.
• Confirm no timestamps, absolute paths, or random values leak into task inputs.
• Build and test the minified variant on CI, not only debug.
• Archive mapping.txt for every shipped build.
• Open the merged manifest after every dependency bump.
• Test on your lowest supported API level with desugaring enabled.
• Verify language, density, and ABI splits with a real bundle install (bundletool or an internal-testing track).
• Keep a Baseline Profile in the release pipeline and benchmark it against CompilationMode.None().

The pipeline is not magic; it is a chain of narrow, inspectable transformations. Once you can say which link failed, “the release build is weird” becomes a ten-minute investigation instead of a lost weekend.

🍎 Share Your Kotlin Code with iOS — Without Rewriting Your App

If “we’ll just build it twice, once per platform” describes how your team ships mobile, I’d recommend “Kotlin Multiplatform for Android Developers” — a 22-chapter, hands-on guide that goes past the sample-project demos and follows the shared module all the way to two app store submissions. No iOS or Swift background required.

It walks through the expect/actual mechanism and source set hierarchy, shared architecture, networking with Ktor, persistence with Room KMP and SQLDelight, Koin dependency injection, Flow and StateFlow with Swift interop (SKIE and Swift Export), Compose Multiplatform versus native SwiftUI, navigation, testing across two runtimes, dual-toolchain CI/CD with Linux and macOS runners, publishing a KMP library, and migrating an existing Android app module by module. Everything builds toward one capstone: an offline-first Expense/Budget Tracker, complete with a pending-sync queue, retry/backoff, and a deployment checklist for both stores.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover.

Originally published on Medium.

This post explains the rule behind that crash, why Kotlin enforces it at runtime, the three legitimate ways to get work onto another dispatcher, and the production failure modes that still bite experienced teams.

What you will take away

• What context preservation means, stated precisely rather than as folklore.
• The one-line fix that covers most cases, and why it beats flowOn.
• How flowOn and channelFlow actually work, including the hidden buffer.
• A test that locks the invariant in so a refactor can’t quietly break it.

The invariant, stated precisely

A cold flow { } is a suspend lambda that the collector runs inside its own coroutine. Every call to emit is a direct, suspending call into the collector's downstream code. The rule is:

emit must be called from the same coroutine context in which collect is running.

“Same context” means the relevant elements match: the dispatcher, plus a compatible Job hierarchy. It is not only about threads, which is why a nested withContext that swaps in a different dispatcher is rejected, while a withContext that doesn't change the effective context passes.

The runtime check lives in the collector wrapper, and it fires on every emit. It is not a debug-only assertion.

Why the rule exists

Downstream operators and your own collect lambda are written as ordinary sequential code. That design depends on three guarantees:

1. Sequential delivery. One value is fully processed before the next arrives.
2. A predictable execution context. A collect { } on Dispatchers.Main can touch views without wrapping every line in withContext(Dispatchers.Main).
3. Safe unsynchronised state. An operator such as scan or onEach can keep a plain var because it is never entered concurrently.

If emit could be called from arbitrary dispatchers, all three break at once. Allowing it would push synchronisation costs onto every operator author and every collector. Kotlin chose the opposite trade: make the producer side responsible, and fail fast when it cheats.

A small clarification of a claim you will see repeated: the invariant is not “all emissions happen on one thread.” Dispatchers can resume a coroutine on different threads between suspension points. The guarantee is about the coroutine context, and about emissions being sequential.

Reproducing the crash

Here is a deliberately ordinary repository for a parcel-tracking app. The broken version is the one many of us write on the first attempt:

class ParcelRepository(
    private val api: ParcelApi,
    private val io: CoroutineDispatcher = Dispatchers.IO,
) {
    // Violates the invariant: emit() is called while the context is `io`.
    fun trackBroken(id: String): Flow<ParcelStatus> = flow {
        withContext(io) {
            emit(api.fetchStatus(id))
        }
    }
}

Collect it from a viewModelScope coroutine (which runs on Dispatchers.Main.immediate) and the first emission throws. The message begins with Flow invariant is violated and then lists the collector's context and the emitter's context side by side, which is the quickest way to see what differed.

Pin the behaviour down with a test. Injecting the dispatcher is what makes this testable:

@Test
fun `emitting from a different dispatcher is rejected`() = runTest {
    val otherDispatcher = StandardTestDispatcher(testScheduler)

    val broken = flow {
        withContext(otherDispatcher) { emit("late") }
    }

    assertFailsWith<IllegalStateException> { broken.first() }
}

Fix 1 (preferred): make the suspend function main-safe

Most of the time you don’t need a different flow builder at all. You need to separate where the work runs from where the value is emitted:

class ParcelRepository(
    private val api: ParcelApi,
    private val io: CoroutineDispatcher = Dispatchers.IO,
) {
    fun track(id: String): Flow<ParcelStatus> = flow {
        val status = withContext(io) { api.fetchStatus(id) }
        emit(status) // back in the collector's context
    }
}

withContext returns before emit runs, so the emission happens in the collector's context. The context switch is a detail of one suspend call, not a property of the whole stream.

Better still, push the dispatcher switch into the data source so every caller benefits:

class ParcelRemoteSource(
    private val service: ParcelService,
    private val io: CoroutineDispatcher = Dispatchers.IO,
) : ParcelApi {
    override suspend fun fetchStatus(id: String): ParcelStatus =
        withContext(io) { service.status(id).toDomain() }
}

// The repository no longer needs a dispatcher, because `api` is main-safe.
class ParcelRepository(private val api: ParcelApi) {
    fun track(id: String): Flow<ParcelStatus> = flow { emit(api.fetchStatus(id)) }
}

This is the convention behind “suspend functions should be main-safe”: callers never have to know which dispatcher a function wants.

Fix 2: flowOn for a stream of blocking or CPU-heavy work

When the producer is a loop, such as polling, reading a file line by line, or decoding frames, wrapping every iteration in withContext is noisy. flowOn moves the entire upstream instead:

class ParcelRepository(
    private val api: ParcelApi,
    private val io: CoroutineDispatcher = Dispatchers.IO,
) {
    // normalised() stands for any pure, CPU-bound extension on ParcelStatus.
    fun poll(id: String, every: Duration = 5.seconds): Flow<ParcelStatus> = flow {
        while (currentCoroutineContext().isActive) {
            emit(api.fetchStatus(id))
            delay(every)
        }
    }
        .map { it.normalised() }      // runs on io
        .flowOn(io)                   // boundary
        .distinctUntilChanged()       // runs in the collector's context
}

Two details deserve attention.

It only affects what is above it. Operators placed after flowOn keep running in the collector's context. A flowOn(io) added at the end of a chain does not rescue a heavy map that was placed below an earlier boundary.

It is not free. To cross the boundary, flowOn runs the upstream in a separate coroutine and hands values over through a channel. With default settings that channel uses Channel.BUFFERED, which is 64 items on the JVM and therefore on Android (tunable through the kotlinx.coroutines.channels.defaultBuffer system property). The producer can therefore run ahead of the collector, which changes your back-pressure story compared with a plain flow. See failure mode 4 below.

If the upstream is already running on the dispatcher you request, the operator can avoid the extra hop, but you should not rely on that when reasoning about buffering.

Fix 3: channelFlow for concurrent or multi-context producers

Sometimes the problem genuinely is “several things produce values and they live on different dispatchers.” That is the job of channelFlow. Here send goes through a Channel, which is safe to call from any coroutine in the producer scope:

class ParcelRepository(
    private val api: ParcelApi,
    private val io: CoroutineDispatcher = Dispatchers.IO,
) {
    fun trackMany(ids: List<String>): Flow<ParcelStatus> = channelFlow {
        val gate = Semaphore(permits = 4) // bound the fan-out
        for (id in ids) {
            launch {
                gate.withPermit {
                    withContext(io) { send(api.fetchStatus(id)) }
                }
            }
        }
    }
}

The semaphore caps how many requests are in flight, but this still creates one coroutine per id. Coroutines are cheap, so that is fine for hundreds of items. For very large lists, prefer flatMapMerge (shown below), which keeps only concurrency collectors active at a time.

The legality of send inside withContext(io) is the key contrast with emit. The collector is not being called by the producer; it is draining a channel from its own coroutine. The invariant still holds. It simply holds on the receiving side.

Notes that matter in review:

• The block returns only after all of its children finish, and then the channel closes. That is why launching children inside the channelFlow scope matters.
• Results arrive in completion order, not list order. If you need the original order, tag each result with its index and sort downstream, or use a different structure.
• For a plain “map each element concurrently” requirement, ids.asFlow().flatMapMerge(concurrency = 4) { id -> flow { emit(api.fetchStatus(id)) } } (inside the same repository) says the same thing with less ceremony.

callbackFlow is channelFlow with an obligation

Bridging a listener API follows the same channel mechanics, plus a rule you must satisfy:

fun connectivity(manager: ConnectivityManager): Flow<Boolean> = callbackFlow {
    val callback = object : ConnectivityManager.NetworkCallback() {
        override fun onAvailable(network: Network) { trySend(true) }
        override fun onLost(network: Network) { trySend(false) }
    }
    manager.registerDefaultNetworkCallback(callback)

    awaitClose { manager.unregisterNetworkCallback(callback) }
}.distinctUntilChanged()

Two platform notes: registerDefaultNetworkCallback requires API 24 (Android 7.0), so on a lower minSdk register a NetworkRequest with registerNetworkCallback instead or guard the call with a Build.VERSION.SDK_INT check, and the manifest needs the ACCESS_NETWORK_STATE permission.

Without awaitClose, the block would finish immediately, the channel would close, and Kotlin throws to tell you the listener would leak.

Choosing between them

A short heuristic to go with the matrix:

1. Can the suspend call itself switch dispatchers? Do that, and keep a plain flow.
2. Is it a long-running sequential producer? Use flowOn.
3. Do multiple coroutines produce, or must values come from several contexts? Use channelFlow.
4. Is a non-coroutine callback the producer? Use callbackFlow.

Failure modes you will actually meet

1. emit inside withContext

Covered above. The tell-tale detail in code review is emit appearing inside the braces of a withContext, launch, or async block in a flow { }.

2. emit from a launched child

This is the same violation, but it hides behind a fork, so it passes your happy-path test:

// Inside ParcelRepository, so `api` resolves.
// Compiles. Throws the moment the child reaches emit().
fun trackManyBroken(ids: List<String>): Flow<ParcelStatus> = flow {
    coroutineScope {
        ids.forEach { id -> launch { emit(api.fetchStatus(id)) } }
    }
}

The child coroutine has a different Job, so the collector rejects the call. The fix is channelFlow with send, or flatMapMerge.

3. flowOn in the wrong place

// The heavy parse still runs on the collector's context.
repo.rawLines()
    .flowOn(Dispatchers.IO)
    .map { parseHeavy(it) }   // below the boundary

Move flowOn so it sits directly after the expensive operators. When in doubt, log Thread.currentThread().name from inside each stage once, and read the output.

4. The hidden buffer

Because flowOn introduces a channel, a fast producer and a slow collector no longer run in lock-step. For "latest state wins" streams such as sensor readings or UI state, you rarely want a queue of stale values:

sensor.readings()
    .flowOn(Dispatchers.Default)
    .conflate()  // keep only the newest value when the collector is busy

For streams where every item matters, set the capacity deliberately instead of inheriting the default: .buffer(capacity = 16, onBufferOverflow = BufferOverflow.SUSPEND).

5. A callbackFlow that never closes properly

Two variants. Forgetting awaitClose causes the exception described earlier. Putting awaitClose { } in place but never unregistering inside it leaks the listener for the life of the process, with no crash to warn you. The unregister call belongs in that trailing block.

A related trap: swallowing exceptions around emit

flow {
    try {
        emit(compute())
    } catch (e: Exception) {   // also catches downstream failures
        emit(fallback())       // now emitting after a downstream error
    }
}

A try/catch around emit also intercepts exceptions thrown by the collector. The flow contract (exception transparency) says the producer must not handle them. Catch around the upstream work, or use the catch operator, which only sees upstream exceptions.

A review checklist you can paste into your PR template

• No emit call sits lexically inside withContext, launch, or async in a flow { }.
• Suspend data-source functions switch dispatchers themselves, with the dispatcher injected.
• Every flowOn is placed directly after the operators it is meant to move.
• Each flowOn has an intentional buffering policy (conflate, buffer, or a documented default).
• Each channelFlow bounds its concurrency and does not launch outside its own scope.
• Each callbackFlow ends with awaitClose and unregisters the listener there.
• A test asserts the happy path with an injected test dispatcher.

🔚 Closing thought

The restriction on flow { } is not an arbitrary limitation. It is what lets map, filter, collect, and your own operators be written as plain sequential Kotlin. Most of the time the right answer is to move the dispatcher switch down into the suspend function. When the shape of the problem is truly concurrent, channelFlow exists because a channel gives you the thread safety that the plain builder deliberately refuses to provide.

📱 Stop Guessing Whether Your Android Code Actually Works

If “we’ll add tests later” is a sentence your team says a little too often, I’d recommend “Mastering Android Testing” — a 35-chapter deep dive into why Android testing is uniquely hard (Activity/Fragment coupling, async complexity, tooling churn) and exactly how to fix it, layer by layer. It walks through architecting for testability, JUnit/Truth/MockK fundamentals, ViewModel and coroutine/Flow testing without flakiness, Compose UI testing and the semantics tree, Espresso and instrumented tests, Room/Retrofit data-layer testing with a full sync-conflict-resolution case study, Robolectric’s real limits, CI pipelines, flaky test triage, and how to build a testing culture that actually survives contact with a deadline.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover.

Originally published on Medium.

That bug lives in a gap between two ideas Kotlin Flow lets you mix freely: state, where only the latest value matters, and events, where every occurrence matters. The mechanism that blurs the line is conflation, and it is not the only way values vanish. This post walks through what conflation is, when it quietly becomes a data-loss bug, and how to pick a primitive that matches the meaning of what you’re sending.

What conflation is

Conflation means that when a producer outpaces its collector, intermediate values are discarded and the collector receives the most recent one. The collector never asks for this; it simply never gets a chance to look at the values it skipped.

conflation-timeline

StateFlow conflates by design. Here is a download screen that updates its progress in a tight loop:

class DownloadViewModel : ViewModel() {

    private val _progress = MutableStateFlow(0)
    val progress: StateFlow<Int> = _progress.asStateFlow()

    fun start() {
        viewModelScope.launch(Dispatchers.Default) {
            for (percent in 1..100) {
                _progress.value = percent   // no suspension point between writes
            }
        }
    }
}

A UI that takes a few milliseconds per frame to render will see only a handful of values (the exact ones depend on dispatcher scheduling and frame timing, so the sequence is nondeterministic), not a hundred distinct values. The only guarantee is that the last value written is eventually delivered. For a progress bar this is the correct behavior: rendering stale numbers faster than the user can read them would only waste CPU. Conflation is the reason StateFlow is cheap, and it is why you can write to it from anywhere without worrying about a slow UI.

Two properties of StateFlow are worth keeping in mind, because they are conflation's quieter cousins:

data class Cart(val items: MutableList<String> = mutableListOf())

val cart = MutableStateFlow(Cart())

cart.value.items.add("green tea")   // same instance, nothing assigned: no emission
cart.value = cart.value              // equal to the current value: ignored

StateFlow compares each new value to the current one with equals and drops it when they match. Mutating an object in place never emits at all. Prefer immutable state and update { it.copy(...) }, which also gives you atomic read-modify-write.

When conflation is a feature

Conflation is exactly right whenever the latest value is the whole truth: a screen’s UI state, a search query, a connectivity flag, a playback position. Skipping the middle changes nothing the user can perceive, and you get natural backpressure handling for free.

The failure begins when something that is semantically an event (navigate, show a dialog, play a sound, confirm a purchase) gets modeled as state.

When conflation is a bug

Failure mode 1: the snackbar that ate itself

A very common shortcut is a nullable field in UI state:

data class CheckoutUiState(val snackbar: String? = null)

// Two things go wrong in the same frame:
_state.update { it.copy(snackbar = "Card declined") }
_state.update { it.copy(snackbar = "Retry limit reached") }

The collector may only ever see the second message, so the user never learns the card was declined. Worse, if the user taps Retry and the same error occurs, snackbar = "Card declined" equals the previous value (assuming it was never cleared), so StateFlow swallows it. The screen looks frozen.

Failure mode 2: a wrong belief about SharedFlow

The usual advice is “use SharedFlow for events", and the usual explanation is that it doesn't conflate. Both halves are only partly true. A default MutableSharedFlow() has replay = 0, extraBufferCapacity = 0 and BufferOverflow.SUSPEND:

private val _effects = MutableSharedFlow<CheckoutEffect>()   // all defaults

suspend fun confirm(orderId: String) {
    _effects.emit(CheckoutEffect.ShowReceipt(orderId))
    _effects.emit(CheckoutEffect.NavigateToOrders)
}

With that configuration, emit suspends until every current subscriber has received the value, so nothing is conflated. Two other things happen instead:

1. A slow subscriber suspends the emitter. A collector that does heavy work in its handler stalls whatever coroutine called emit.
2. With no subscribers, the value is gone. extraBufferCapacity only buffers values for existing subscribers that are lagging. When nobody is collecting and replay = 0, emit returns immediately and the event evaporates, no matter how large the extra buffer is. Only a replay > 0 cache retains values for future collectors, and it does so by replaying the last n values to every new collector, which is the wrong semantics for one-shot effects (a rotated screen would show the receipt again). That is the checkout bug: the user had backgrounded the app during the payment call, the lifecycle-aware collector was stopped, and ShowReceipt went nowhere.

tryEmit makes it worse: on a flow with no buffer and active subscribers it returns false when it cannot hand the value over, and most call sites ignore that result.

Failure mode 3: collectLatest is conflation with a cancel button

collectLatest cancels the handler for the previous value when a new one arrives. That is perfect for "search as you type" and dangerous for effects:

effects.collectLatest { effect ->
    when (effect) {
        is CheckoutEffect.ShowReceipt -> {
            delay(300)                         // let the transition finish
            receiptSheet.show(effect.orderId)  // never reached if another effect lands first
        }
        CheckoutEffect.NavigateToOrders -> navigator.toOrders()
    }
}

If NavigateToOrders arrives within 300 ms, the receipt handler is cancelled mid-flight. The same happens with .conflate() and .buffer(Channel.CONFLATED), as well as with SharedFlow configured with DROP_OLDEST or DROP_LATEST. Each of these is a deliberate "drop it" policy. None of them belongs on an effect stream.

Comparing your options

Notice what the matrix says about the two SharedFlow rows in the middle. Neither conflates, and both still lose an event emitted into an empty room. If you need delivery guarantees across a lifecycle gap, a buffer on the SharedFlow isn't enough: you need something that holds events for a collector that isn't there yet.

Fixes that actually hold

Option A: a buffered SharedFlow when a collector is always present

If your collector is long-lived (a repository, a coordinator, a service-scoped bus), you can make a SharedFlow lossless under bursts:

private val _effects = MutableSharedFlow<CheckoutEffect>(
    extraBufferCapacity = 64,                     // absorb bursts
    onBufferOverflow = BufferOverflow.SUSPEND,    // back-pressure, never drop
)
val effects: SharedFlow<CheckoutEffect> = _effects.asSharedFlow()

This removes conflation and protects against slow collectors, but it does not help when nobody is subscribed. For UI work, that disqualifies it.

Option B: a Channel for single-consumer UI effects

A Channel keeps elements until someone receives them, so effects emitted while the screen is stopped are waiting when it comes back:

class CheckoutViewModel(
    private val payments: PaymentsRepository,
) : ViewModel() {

    private val _effects = Channel<CheckoutEffect>(capacity = Channel.BUFFERED)
    val effects: Flow<CheckoutEffect> = _effects.receiveAsFlow()

    fun confirm(orderId: String) {
        viewModelScope.launch {
            payments.confirm(orderId)
            _effects.send(CheckoutEffect.ShowReceipt(orderId))
            _effects.send(CheckoutEffect.NavigateToOrders)
        }
    }
}

And on the UI side, collect only while the screen is visible:

viewLifecycleOwner.lifecycleScope.launch {
    viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.effects.collect { effect -> render(effect) }
    }
}

A few details separate a working version from a subtly broken one:

• Use receiveAsFlow(), not consumeAsFlow(). consumeAsFlow() cancels the channel when its collector is cancelled, and repeatOnLifecycle cancels its collector every time the screen stops. After the first rotation or backgrounding, your channel is closed and later sends throw or are lost.
• Prefer BUFFERED over UNLIMITED. An unlimited channel never suspends, so trySend always succeeds. If the UI is gone for a long time or an effect source is chatty, memory grows without bound. A bounded buffer makes the producer's behavior explicit.
• A bounded buffer shifts the failure mode; it doesn’t remove it. Channel.BUFFERED holds 64 elements by default. If the screen stays gone while more than that are queued, further send calls suspend, and each suspended coroutine stays alive in viewModelScope until the UI returns. For effects triggered by user taps this is rarely reachable, but if a producer can outrun the UI for long periods, decide on purpose: use trySend and handle the failure, coalesce at the source, or move that data to state.
• A Channel has fan-out semantics. Two collectors will split the elements between them instead of each seeing all of them. If more than one consumer needs every effect, a Channel is the wrong tool.
• Handlers should be short and non-suspending. An element is considered delivered once it’s received. If the screen stops while a suspending handler is half-way done, that effect is not redelivered.

Option C: make the effect part of the state

The Android architecture guidance leans toward representing one-off UI events as state that the UI acknowledges. This sidesteps the question of “who is collecting” entirely, but you must design it so conflation can’t hurt you. A single nullable field loses messages. A queue with identities does not:

import java.util.concurrent.atomic.AtomicLong

data class PendingEffect(val id: Long, val effect: CheckoutEffect)

data class CheckoutUiState(
    val total: Money = Money.ZERO,
    val pending: List<PendingEffect> = emptyList(),
)

class CheckoutViewModel : ViewModel() {

    private val _state = MutableStateFlow(CheckoutUiState())
    val state: StateFlow<CheckoutUiState> = _state.asStateFlow()

    private val nextId = AtomicLong(0)   // safe even if enqueue() is called off the main thread

    private fun enqueue(effect: CheckoutEffect) {
        val id = nextId.getAndIncrement()   // outside update{}: its lambda can be re-run on CAS retry
        _state.update { it.copy(pending = it.pending + PendingEffect(id, effect)) }
    }

    fun onEffectHandled(id: Long) {
        _state.update { s -> s.copy(pending = s.pending.filterNot { it.id == id }) }
    }
}

Conflation is harmless here because each emission carries the whole queue. The UI renders pending.firstOrNull() and calls onEffectHandled(id) when done. The cost is more boilerplate and the need to make handlers idempotent: after a configuration change, the same pending effect may be rendered again until it is acknowledged.

A decision path you can apply in code review

Testing for the loss, not around it

The reason this bug ships is that the natural unit test collects first and emits second, which is the one ordering where a plain SharedFlow works. Flip it: send while nobody is listening.

import app.cash.turbine.test
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.test.StandardTestDispatcher
import kotlinx.coroutines.test.TestDispatcher
import kotlinx.coroutines.test.advanceUntilIdle
import kotlinx.coroutines.test.resetMain
import kotlinx.coroutines.test.runTest
import kotlinx.coroutines.test.setMain
import org.junit.Rule
import org.junit.Test
import org.junit.rules.TestWatcher
import org.junit.runner.Description
import kotlin.test.assertEquals

@OptIn(ExperimentalCoroutinesApi::class)
class MainDispatcherRule(
    val dispatcher: TestDispatcher = StandardTestDispatcher(),
) : TestWatcher() {
    override fun starting(description: Description) = Dispatchers.setMain(dispatcher)
    override fun finished(description: Description) = Dispatchers.resetMain()
}

class CheckoutViewModelTest {

    @get:Rule
    val mainDispatcherRule = MainDispatcherRule()

    @Test
    fun `receipt effect survives a stopped UI`() = runTest(mainDispatcherRule.dispatcher) {
        val vm = CheckoutViewModel(FakePayments())

        vm.confirm("A-17")        // launches on viewModelScope (Dispatchers.Main)
        advanceUntilIdle()        // let both sends complete before anyone collects

        vm.effects.test {         // Turbine: collector arrives late, on purpose
            assertEquals(CheckoutEffect.ShowReceipt("A-17"), awaitItem())
            assertEquals(CheckoutEffect.NavigateToOrders, awaitItem())
            cancelAndIgnoreRemainingEvents()
        }
    }
}

Passing the rule’s dispatcher into runTest makes the test body and viewModelScope share one scheduler, so advanceUntilIdle() really does run the ViewModel's coroutine. Against a MutableSharedFlow<CheckoutEffect>() the same test fails with a Turbine timeout on the first awaitItem(), which reproduces the production symptom.

For StateFlow assertions, remember the opposite: assert on the final value or on the properties you really need, because intermediate emissions can legitimately be skipped.

Checklist

• Ask of every flow: is this a value or an occurrence? Values go in StateFlow; occurrences need delivery semantics.
• Never ship an effect through a nullable state field. Use a queue with ids if you want effects in state.
• A SharedFlow is a broadcast to whoever is listening now. It is not a mailbox.
• Treat conflate(), collectLatest, DROP_OLDEST and DROP_LATEST as explicit data-loss opt-ins.
• For single-consumer UI effects, use Channel(BUFFERED) with receiveAsFlow() and repeatOnLifecycle.
• Write the test that emits before anyone collects.

Conflation is not the villain. It makes UI state cheap and robust. The problem is applying it to things that were never meant to be summarized by their latest value.

🧵 Stop Treating Coroutines Like Magic Keywords

If “just add launch and hope” describes how your team handles concurrency, I’d recommend “Kotlin Coroutines Under the Hood” — a 25-chapter deep dive that goes past the syntax and down to the bytecode: the Continuation-Passing Style transform, the compiler-generated state machine, and exactly why a suspended coroutine costs a few dozen bytes while a blocked thread costs a megabyte.

It walks through structured concurrency and Job hierarchies, dispatcher internals (Default vs IO vs Unconfined), cooperative cancellation and exception aggregation, Flow’s cold-stream semantics and the full operator vocabulary, StateFlow/SharedFlow’s hot-broadcast model, Channels and fan-in/fan-out patterns, Mutex/Semaphore/actors for shared state, and a complete Android case study retrofitting a legacy callback-driven app onto coroutines and Flow — including a 100,000-coroutines-vs-100,000-threads benchmark lab you can run yourself.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover.

Originally published on Medium.

This post separates three ideas that tend to get blurred together:

• Composition: the first execution of a composable when it enters the tree.
• Recomposition: a later, targeted re-execution after state it read has changed.
• Deferred composition: composing children during the layout phase, because their content depends on constraints or sizes that only exist at that point.

We will go through each one, look at the code that makes the distinction visible, and finish with six failure modes I have seen in production apps.

Where these ideas sit in a frame

Compose renders a frame in three phases: composition, layout, drawing. Composition and recomposition live in the first phase. Deferred composition is the odd one out, because it reaches forward and runs inside the second.

Keep that picture in mind. Every section below is a closer look at one of its arrows.

Composition: the first run

When a composable enters the tree for the first time, the runtime executes its body, executes every composable it calls, and records what happened in a structure called the slot table. The slot table stores groups, remembered values, and the information needed to diff against on the next run.

@Composable
fun ProfileHeader(user: User) {
    // Runs during initial composition, and again only if something invalidates it.
    val formatter = remember { DateFormat.getDateInstance(DateFormat.MEDIUM) }

    Column {
        Avatar(url = user.avatarUrl)
        Text(user.displayName)
        Text(formatter.format(user.joinedAt))
    }
}

Two clarifications are worth making, because the simplified version (“composition happens once”) causes real mistakes.

Once per entry, not once per screen. If a composable leaves the tree and comes back, it is a fresh composition and remember starts empty. An if (expanded) { Details() } branch, a navigation destination being popped, or a lazy item scrolling far enough away can all trigger this. State that must survive belongs in rememberSaveable, a ViewModel, or a hoisted holder.

The body is not a place for side effects. The runtime is allowed to run, abandon, and re-run a composition. Writing to a database or firing analytics from the body is a bug waiting for a retry to expose it. Use LaunchedEffect, DisposableEffect, or SideEffect, which have defined timing.

// Fragile: may run more than once, or run for a composition that is thrown away.
@Composable
fun ScreenViewed(name: String) {
    analytics.track("screen_viewed", name)
}

// Correct: tied to the composition actually being applied and to the key.
@Composable
fun ScreenViewed(name: String) {
    LaunchedEffect(name) { analytics.track("screen_viewed", name) }
}

Recomposition: the targeted re-run

Recomposition is not “redraw the screen.” It is the runtime re-executing only the scopes that were invalidated, then reusing everything else.

A scope becomes invalid when a snapshot State it read during composition changes. The runtime finds the nearest enclosing restartable scope and queues it. When that scope re-runs, each child call is compared to its previous inputs. If the inputs are equal and the child is skippable, the call is skipped without executing the body.

A small instrument makes this visible. Drop it into any suspect composable while debugging:

import android.util.Log

@Composable
fun RecompositionLog(tag: String) {
    val count = remember { intArrayOf(0) }
    SideEffect {
        count[0]++
        Log.d("Recomposition", "$tag ran ${count[0]} time(s)")
    }
}

SideEffect fires only for compositions that are actually applied, so recompositions the runtime abandons are not counted. That is what you want when measuring user-visible work, but it means the number can be lower than how many times the body executed.

What decides whether a child is skipped

Skipping depends on the inputs being stable and equal. A parameter type the compiler cannot prove stable (a plain List<T>, a class from a module without the Compose compiler, a class with var properties) used to make the whole call non-skippable. Recent Compose compiler versions enable strong skipping by default (it became the default with Kotlin 2.0.20, via the Compose compiler Gradle plugin; on older setups it is an opt-in flag). With it on, every restartable composable becomes skippable: stable parameters are compared with equals(), and unstable ones are compared by instance identity (===). Lambdas that capture unstable values are also memoized. That softens the problem but does not remove it: a new List instance on every parent pass is a different instance, so it still defeats skipping.

// Allocates a new list each time the parent runs. Equal contents, different instance.
@Composable
fun Inbox(messages: List<Message>) {
    MessageList(items = messages.filter { !it.archived })
}

// Cache the derived value against the thing it depends on.
@Composable
fun Inbox(messages: List<Message>) {
    val visible = remember(messages) { messages.filter { !it.archived } }
    MessageList(items = visible)
}

Where you read state matters more than how often it changes

This is the single highest-leverage habit in Compose performance. The scope that reads the value is the scope that recomposes.

// Reads the offset in the body: every scroll pixel recomposes ScrollTitle.
@Composable
fun ScrollTitle(listState: LazyListState) {
    val offset = listState.firstVisibleItemScrollOffset
    Text(
        text = "Library",
        modifier = Modifier.padding(top = (offset / 4).dp)
    )
}

// Defer the read into the layout phase. Composition is untouched while scrolling.
@Composable
fun ScrollTitle(listState: LazyListState) {
    Text(
        text = "Library",
        modifier = Modifier.offset {
            IntOffset(x = 0, y = listState.firstVisibleItemScrollOffset / 4)
        }
    )
}

When you only need a threshold, not the raw value, derivedStateOf collapses thousands of changes into a handful of invalidations:

val showJumpToTop by remember {
    derivedStateOf { listState.firstVisibleItemIndex > 3 }
}

Note the vocabulary here. Moving a read into a lambda modifier is a deferred state read. It is related to, but not the same as, deferred composition, which is the subject of the next section.

Deferred composition: composing during layout

Normally composition finishes before layout starts. That ordering breaks down when the content of a child depends on information layout produces: the available width, the viewport height, or the measured size of a sibling. Composing first and measuring later cannot express that.

Compose solves this with subcomposition: a layout can call subcompose while it is measuring, which creates (or updates) an independent child composition on demand.

Two things you already use do this:

• LazyColumn and friends only compose the items that fit the viewport. They can only know which items fit once layout knows the viewport size, so item composition is driven from the measure pass, with some prefetching to hide the latency.
• BoxWithConstraints and Scaffold use subcomposition so their slot content can see constraints or sibling sizes.

SubcomposeLayout is the explicit, general form.

A header-and-body layout that survives real constraints

The textbook version of this layout works in a demo and fails in an app. This one handles loose constraints, unbounded parents, and windows too small for the header:

private enum class Slot { Header, Body }

@Composable
fun HeaderBodyLayout(
    modifier: Modifier = Modifier,
    header: @Composable () -> Unit,
    body: @Composable () -> Unit,
) {
    SubcomposeLayout(modifier) { incoming ->
        // Children may be smaller than the slot we were offered.
        val loose = incoming.copy(minWidth = 0, minHeight = 0)

        val headerPlaceables = subcompose(Slot.Header, header).map { it.measure(loose) }
        val headerHeight = headerPlaceables.maxOfOrNull { it.height } ?: 0

        // Remaining space for the body: clamp at zero, and respect an unbounded parent.
        val bodyMaxHeight = if (incoming.hasBoundedHeight) {
            (incoming.maxHeight - headerHeight).coerceAtLeast(0)
        } else {
            Constraints.Infinity
        }
        val bodyPlaceables = subcompose(Slot.Body, body)
            .map { it.measure(loose.copy(maxHeight = bodyMaxHeight)) }
        val bodyHeight = bodyPlaceables.maxOfOrNull { it.height } ?: 0

        val width = (maxOf(
            headerPlaceables.maxOfOrNull { it.width } ?: 0,
            bodyPlaceables.maxOfOrNull { it.width } ?: 0,
        )).coerceIn(incoming.minWidth, incoming.maxWidth)
        val height = (headerHeight + bodyHeight)
            .coerceIn(incoming.minHeight, incoming.maxHeight)

        layout(width, height) {
            headerPlaceables.forEach { it.placeRelative(0, 0) }
            bodyPlaceables.forEach { it.placeRelative(0, headerHeight) }
        }
    }
}

One caveat about the unbounded branch. When the parent offers infinite height, the body is measured with Constraints.Infinity. That keeps the layout itself from crashing, but it does not make the body's content safe: a LazyColumn placed in body under an unbounded parent (for example inside verticalScroll) will still throw, for the same reason as failure mode 2 below. The layout is defensive about its own math, not about what you put in the slots. Place it under a bounded parent, or keep scrollable content out of body in that situation.

Usage reads like any other layout, and the body can be a lazy list that sizes itself to whatever the header left behind (here fillMaxSize gives it a bounded height):

HeaderBodyLayout(
    modifier = Modifier.fillMaxSize(),
    header = { SearchBar(query, onQueryChange) },
    body = { ResultsList(results) },
)

Why not just measure the header with onSizeChanged?

You can, and many apps do:

var headerHeight by remember { mutableIntStateOf(0) }
Column {
    Header(Modifier.onSizeChanged { headerHeight = it.height })
    Body(maxHeight = with(LocalDensity.current) { headerHeight.toDp() })
}

The cost: the size is only known after the first layout, so the body renders once with a wrong value, then a state write triggers recomposition, then it renders again. You get an extra pass and often a visible one-frame jump. Subcomposition removes the round trip because the dependency is resolved inside a single measure pass.

The three at a glance

Six failure modes worth memorizing

Four of these deserve a closer look.

1. Negative or unbounded remaining space

Constraints validates its arguments. A maxHeight below zero throws, and so does a maxHeight smaller than minHeight. The naive constraints.maxHeight - header.height hits this on split-screen windows, landscape phones, or when the IME is open. The fix is in the layout above: reset minHeight, clamp with coerceAtLeast(0), and branch on hasBoundedHeight.

2. Lazy content under a scroller

// Crashes at measure time: the lazy list is offered infinite height.
Column(Modifier.verticalScroll(rememberScrollState())) {
    Header()
    LazyColumn { items(rows) { RowItem(it) } }
}

Compose throws an IllegalStateException about a vertically scrollable component measured with infinite maximum height. Either give the inner list a bounded height, or make the whole screen one LazyColumn with a header item.

3. Unkeyed lazy items

Without keys, item identity is positional. Insert at the top and every remembered value shifts one row. Provide a stable key, and a content type if rows differ in structure so the runtime can reuse compatible compositions:

LazyColumn {
    items(
        items = messages,
        key = { it.id },
        contentType = { it.kind },
    ) { message ->
        MessageRow(message)
    }
}

4. Reaching for SubcomposeLayout by default

Subcomposition is more expensive than a plain Layout, and SubcomposeLayout does not support intrinsic measurements by default. Putting BoxWithConstraints in every row of a long list is a common way to turn smooth scrolling into dropped frames. Use it when the composition genuinely depends on constraints, not when you only need to measure something. If a modifier or a plain Layout can do the job, prefer that.

A debugging checklist

When something feels slow or wrong, ask in this order:

1. Which phase is this happening in? The Layout Inspector’s recomposition counts tell you whether composition is the problem or layout is.
2. Which scope reads the changing value? If a fast-changing State is read high in the tree, move the read down or into a lambda.
3. Are the inputs equal? Log with the RecompositionLog helper, then look for fresh List, lambda, or object instances created on every pass.
4. Is subcomposition justified? If a child’s content does not depend on constraints, a plain layout is cheaper.
5. What happens at the edges? Zero height, unbounded height, a window half the size you tested, and a reordered list.

🔚 Takeaways

• Composition is when the tree is built. Treat it as a pure function that may run more than once.
• Recomposition is a scoped re-run keyed on what was read. Where you read state decides what recomposes.
• Deferred composition exists for exactly one reason: some children cannot be composed until layout knows something. Use it for that, and write its constraint math defensively.

If you internalize the “which phase, which scope, which trigger” triple, most Compose performance and correctness bugs become short investigations rather than long ones.

📱 Level Up Your Android System Design Game

If you’re prepping for a senior Android role and system design rounds are the part that makes you sweat, I highly recommend “Mastering Android System Design” — a 37-chapter playbook that treats Android like the constrained runtime it actually is, not a small server. It covers Binder IPC, ART’s GC, process death, and background execution limits, then walks through the CRDDS interview framework and 13 full worked case studies (chat, ride-hailing, video streaming, payments, and more) carried end-to-end through API design, offline sync, and the Android-specific edge cases that trip candidates up mid-interview.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover.

Originally published on Medium.

This post lays out what a remember call does at runtime, which workloads justify it, which don't, and the bugs that show up when it is misused. In my experience, most of those bugs come from over-using remember, not from forgetting it.

What happens at a remember call site

remember is an inline function, so your trailing block is not allocated as a function object. At each call site the compiler produces logic that behaves roughly like this:

// What you write
val sections = remember(transactions) {
    transactions.groupBy { it.date }.toSortedMap(reverseOrder())
}

// Roughly what executes (simplified; mirrors Composer.cache in the runtime)
val dirty = composer.changed(transactions)              // compares against the key kept in the slot table, updates it if different
val stored = composer.rememberedValue()                 // then reads the value slot
val sections = if (dirty || stored === Composer.Empty) {
    transactions.groupBy { it.date }.toSortedMap(reverseOrder())
        .also { composer.updateRememberedValue(it) }
} else {
    stored as SortedMap<LocalDate, List<Transaction>>
}

The key comparison is the argument to cache, so it is evaluated before the value slot is read. The comparison itself goes through changed, which relies on equals().

Three separate costs fall out of that:

1. Reuse cost. One equals()-based comparison per key against the key stored in the slot table, plus one read of the value slot. You pay this on every composition pass that reaches the call site, even when nothing changed. (Most equals() implementations return quickly for the same instance, but that is a property of the key type, not something remember guarantees.)
2. Recompute cost. The reuse cost, plus your block, plus a slot write.
3. Standing cost. The stored value and its keys stay referenced for as long as the call site remains in the composition. This is a memory cost, and it is the one people overlook.

The reuse cost is small: roughly tens of nanoseconds on current hardware. I am deliberately stating an order of magnitude and nothing tighter. The real figure depends on how many keys you pass, how expensive their equals() is, and the device, so benchmark your own case instead of trusting any number in an article.

Cost spectrum

The question to ask is not “is this slow in absolute terms?” It is “is this slow compared with what I pay on every pass, and does anything downstream depend on the result’s identity?”

Cases where it earns its place

Grouping, sorting, and reshaping collections

@Composable
fun TransactionFeed(transactions: List<Transaction>, currency: Currency) {
    // Tracks per-app language switching; the compat call also covers minSdk < 24
    val locale = ConfigurationCompat.getLocales(LocalConfiguration.current).get(0) ?: Locale.getDefault()
    // A miss costs a pass over every row plus map allocation.
    // A hit costs a slot read and one key comparison.
    val sections = remember(transactions) {
        transactions
            .groupBy { it.date }
            .toSortedMap(compareByDescending { it })
    }
    // Locale is a key, otherwise the formatter would keep the old language after a switch
    val money = remember(currency, locale) {
        NumberFormat.getCurrencyInstance(locale).apply { this.currency = currency }
    }

    LazyColumn {
        sections.forEach { (date, rows) ->
            stickyHeader(key = date) { DayHeader(date) }
            items(rows, key = { it.id }) { TransactionRow(it, money) }
        }
    }
}

Grouping, sorting, mapping to display models, and building formatted text from collections are all comfortably above the cutoff.

Three notes on this sample. First, the locale lookup is a cheap read, so it is deliberately not wrapped in remember. Second, anything derived from the environment (locale, density, layout direction) belongs in the key list, as the formatter shows. Third, on older foundation releases stickyHeader is experimental and needs @OptIn(ExperimentalFoundationApi::class); recent releases no longer require it, so check the version you ship.

Objects that are costly to build but cheap to use

Formatters, Regex, Paint, Path, and gradient Brush objects fit this pattern.

@Composable
fun RingMeter(progress: Float, colors: List<Color>) {
    val sweep = remember(colors) { Brush.sweepGradient(colors) }
    Canvas(Modifier.size(96.dp)) {
        drawArc(
            brush = sweep,
            startAngle = -90f,
            sweepAngle = 360f * progress,
            useCenter = false,
            style = Stroke(width = 10.dp.toPx(), cap = StrokeCap.Round),
        )
    }
}

One refinement: if the object has no inputs at all and is immutable, thread-safe, and independent of context, configuration, and density, skip remember and hoist it to a private val at file level. It is built once per process instead of once per call site.

private val HexColor = Regex("^#[0-9a-fA-F]{6}$")   // beats remember { Regex(...) }

That condition is strict, and it rules out several objects from the list above. Path and Paint are mutable, so a shared instance invites cross-composable interference (a reset() in one place corrupts another). NumberFormat and SimpleDateFormat are not thread-safe and follow the locale. Anything sized by density or layout belongs in remember with the right keys. Keep those at the call site, and hoist only the plain immutable constants.

Allocations whose identity matters downstream

A primitive sum allocates nothing. A freshly built Brush, List, or PaddingValues on every pass allocates, and it also gives each child a new instance to compare. If the child takes that instance as a parameter of an unstable type, or you are not running with Strong Skipping, the child recomposes each time.

This is why a pure “under 1 µs, skip it” rule is too blunt. The better test has two halves: is the work heavy, or does a new instance change what downstream code sees?

Cases where it is dead weight

Trivial expressions

// ❌ Each of these costs less than the slot machinery wrapped around it
val isEmpty   = remember(items) { items.isEmpty() }
val total     = remember(a, b) { a + b }
val isLoading = remember(state) { state is UiState.Loading }

// ✅
val isEmpty   = items.isEmpty()
val total     = a + b
val isLoading = state is UiState.Loading

Property reads, type checks, equality checks, and simple arithmetic all belong here. The wrapped version is longer to read and adds a slot to the table to save nothing.

Callbacks, once Strong Skipping is on

// ❌ Redundant with Strong Skipping
val onRetry = remember { { presenter.reload() } }

// ✅
val onRetry = { presenter.reload() }

Strong Skipping is the default from Kotlin 2.0.20 with the Compose compiler plugin. It lets composables with unstable parameters skip, and it auto-remembers lambdas created inside composable functions. Captures that are stable are compared with equals(); unstable ones are compared by reference (===), which the compiler does through an identity-based variant of the key check (changedInstance) rather than plain changed.

Two limits to keep in mind:

• The automatic memoization applies to lambdas created within composable functions. A lambda built in a plain class or produced by a top-level factory gets no such treatment.
• @DontMemoize turns it off for a given lambda, and @NonSkippableComposable turns off skipping for a composable. If you have used either, the "write it plainly" advice no longer applies at that site.

The hand-rolled remember here is also riskier than the redundant one, as the first failure mode below shows.

Decision flow

Failure modes

1. Stale capture from an unkeyed block

This is the bug I see most often, and it is the dark side of “memoize my callback”.

@Composable
fun TaskRow(task: Task, onToggle: (TaskId) -> Unit) {
    // ❌ Pins the first task's id and the first onToggle for as long as this call site lives
    val toggle = remember { { onToggle(task.id) } }
    Checkbox(checked = task.done, onCheckedChange = { toggle() })
}

After a reorder or a data refresh, the checkbox toggles the wrong task. Strong Skipping cannot save you, because an explicit unkeyed remember asks for a value that never invalidates. Delete it, or key it on every captured value. For effects that run for a long time and must see the newest callback, reach for rememberUpdatedState.

2. A key that is mutated in place

remember invalidates when equals() says the key changed, and an instance always equals itself.

val picked = remember { mutableListOf<TagId>() }
// ❌ Same instance forever, so this summary is computed once
val summary = remember(picked) { picked.sorted().joinToString() }

// ✅ Snapshot-aware list, with a derived value that tracks reads
val picked = remember { mutableStateListOf<TagId>() }
val summary by remember { derivedStateOf { picked.sorted().joinToString() } }

A plain MutableList also gives Compose no signal to recompose, so you end up with stale UI and a stale cache together.

3. A key that costs as much as the work

List.equals compares element by element. If the caller rebuilds an equal-but-new list on every pass, your key check traverses all of it.

// ❌ Equal-but-new list each pass: an O(n) comparison to avoid an O(n) map
val cards = remember(articles) { articles.map(::toCardModel) }

On a miss you can pay the comparison up to the first difference and then the full recompute, so the cache is a wash at best. Two fixes beat a clever key:

• Produce cards upstream (a ViewModel, or a StateFlow with map) so the composable receives the finished value.
• Or key on something cheap that changes whenever the data does: a revision counter, a version id, or a stable content hash computed once when the data is created.

4. Heavy work still blocks the main thread

remember makes repeats cheap. It does nothing about the first run, which happens synchronously during composition.

// ❌ Highlighting a large file during the first composition delays the frame
val highlighted = remember(source) { SyntaxHighlighter.highlight(source) }

// ✅ Move it off the main thread, with an explicit loading state
val highlighted by produceState<AnnotatedString?>(initialValue = null, source) {
    value = withContext(Dispatchers.Default) { SyntaxHighlighter.highlight(source) }
}

produceState runs its coroutine on the composition's dispatcher, so the withContext hop is what moves the work off the main thread. When source changes, the previous coroutine is cancelled, but cancellation only takes effect if the work cooperates, so call ensureActive() inside long loops in the highlighter.

If several screens need the same result, a ViewModel is usually a better home than any composable.

5. State vanishes when the call site leaves composition

remember survives recomposition. It does not survive an item scrolling out of a LazyColumn, a destination popping off the back stack, or an activity being recreated.

// Cleared on rotation, and when the item scrolls away and returns
var draft by remember { mutableStateOf("") }

// Survives configuration change and process death (for Saver-compatible types)
var draft by rememberSaveable { mutableStateOf("") }

State that has to outlive the UI element entirely should be hoisted into a state holder or ViewModel.

6. Lingering references

The slot retains the value and the keys. Remember a decoded image, a large collection, or anything that captures an Activity, and it stays reachable while the call site lives.

// ❌ Holds a full-size bitmap for as long as the call site lives
val thumbnail = remember(uri) { ThumbnailLoader.decode(context, uri) }

The remembered value is what stays alive, so make sure the decoded result does not itself hold the Activity. Pass LocalContext.current.applicationContext into loaders that keep a reference.

Narrow the scope, prefer an image-loading library built for this job, and if the object owns a resource, implement RememberObserver (or use DisposableEffect) so cleanup runs in onForgotten or onDispose.

remember and derivedStateOf solve different problems

val listState = rememberLazyListState()

// ❌ Reads the index in composition, so every index change recomposes this scope,
//    and remember(key) cannot help because the key changes each time too.
val showJumpToTop = listState.firstVisibleItemIndex > 3

// ✅ Recomposes only when the Boolean actually flips
val showJumpToTop by remember {
    derivedStateOf { listState.firstVisibleItemIndex > 3 }
}

Use remember(keys) when inputs change rarely and the work is heavy. Use derivedStateOf when inputs change frequently but the output changes rarely. A derivedStateOf itself is normally wrapped in remember, and that particular remember is almost always justified.

Verify instead of guessing

A rule of thumb ends arguments quickly and settles edge cases poorly. For the edge cases:

• Layout Inspector recomposition counts reveal children that recompose more than you expect, which is the typical symptom of an identity problem.
• Macrobenchmark with FrameTimingMetric tells you whether work inside composition causes jank on a cold first frame.
• Microbenchmark the block on a mid-range phone, not your daily driver, to learn whether it takes nanoseconds or microseconds.
• Compose compiler reports (enabled through reportsDestination) show what the compiler considers stable and skippable, which settles most callback and parameter questions.

A working checklist

• Cache heavy transformations (group, sort, map, parse, format), objects that are costly to construct, and allocations whose identity affects children.
• Skip remember for arithmetic, property reads, type and equality checks, and callbacks created inside composables under Strong Skipping.
• Hoist to a file-level val anything with no inputs.
• List every value the block reads as a key, and keep those keys immutable and cheap to compare.
• Reach for derivedStateOf when the input changes more often than the output.
• Move heavy work off the main thread, because remember only caches it.
• Use rememberSaveable or hoist state when it must outlive the call site.

remember is inexpensive, not free, and a cached value that is wrong costs far more than a recomputed one. If you cannot name what a particular remember saves, remove it and see whether anything actually gets slower.

📱 Crack Your Next Android Interview

If you’re targeting a senior Android role at a FAANG or top-tier MNC, syntax knowledge alone won’t get you through the loop. I highly recommend “Cracking Top MNC Android Interviews” — a senior-level playbook covering framework internals, Jetpack Compose, coroutines, Android-specific system design, and DSA reframed around real mobile constraints, to help you walk into bar-raiser rounds ready.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover.

Originally published on Medium.

This post answers that with idiomatic Kotlin, and with the failure modes that only show up once the screen has real data, real rotation, and real users.

🧠 TL;DR (Too Long; Didn’t Read)

• State<T> is a read-only, observable handle. Compose tracks reads of .value.
• MutableState<T> adds a setter. A write invalidates every scope that read it.
• SnapshotStateList<T> is an observable list: in-place mutation is tracked, so you don't copy the list on every change.
• For primitives, prefer mutableIntStateOf (and the Long/Float/Double variants) and read through .intValue or the by delegate. Otherwise you still box.

1. The type family

Two things in that picture trip people up:

1. IntState is State<Int> specialized for primitives, not the generic State<T>. MutableIntState is both an IntState and a MutableState<Int>. It can be passed anywhere a State<Int> is expected, but the primitive-specialized accessors live on IntState.
2. SnapshotStateList<T> implements MutableList<T>. It is not a State<List<T>>. Compose observes the list object itself, not a .value wrapper around it.

State<T>: a read-only window

val count: State<Int> = mutableIntStateOf(0)

State<T> exposes one property: val value: T. Reading it inside a composable (or inside a derivedStateOf, snapshotFlow, or LaunchedEffect block that runs under snapshot observation) registers a dependency.

The practical use is API design. Keep the mutable handle private and expose the read-only one:

class CounterViewModel : ViewModel() {
    private val _count = mutableIntStateOf(0)
    val count: IntState get() = _count          // read-only to the UI

    fun increment() { _count.intValue++ }
}

Note the type is IntState, not State<Int>. That keeps the primitive read path available to callers.

One caveat worth stating plainly: State<T> is read-only to you, not immutable. If something else holds the MutableState and writes to it, your State reference changes underneath you. That's the point of the abstraction, but it's not a snapshot of a value.

MutableState<T>: reads and writes

val count: MutableState<Int> = mutableStateOf(0)
count.value = 5   // invalidates every scope that read count.value

Two behaviors matter here:

Writes are filtered by an equality policy. mutableStateOf defaults to structuralEqualityPolicy(), so writing a value that is equals() to the current one does nothing. No invalidation, no recomposition. That's usually what you want, and it's exactly why mutating an object in place (section 5) is invisible.

Writes are cheap; reads are the expensive part to get wrong. A write marks dirty scopes. The actual re-execution happens later, in the next recomposition pass. On a normal Android UI that is the next frame; in unit tests or with a custom frame clock it runs when that clock ticks.

The consequence is that where you read matters more than where you write. Reading count.value in a parent composable and passing the Int down makes the parent the reader, so the whole parent scope reruns. Passing the State (or a lambda { count.value }) down defers the read to the child, so only the child reruns.

@Composable
fun Screen(count: IntState) {
    // ❌ Parent reads on every change: Screen and everything under it reruns
    // Header(count.intValue)

    // ✅ Read is deferred into Header's own scope
    Header(countProvider = { count.intValue })
}

@Composable
private fun Header(countProvider: () -> Int) {
    Text("Count: ${countProvider()}")
}

2. mutableIntStateOf vs mutableStateOf<Int>: the boxing story, accurately

The common one-liner is “mutableStateOf(0) boxes, mutableIntStateOf(0) doesn't." That's directionally right, but it hides a trap.

val a = mutableStateOf(0)       // generic MutableState<Int>: value stored as java.lang.Integer
val b = mutableIntStateOf(0)    // MutableIntState: value stored as a primitive int

The generic version stores a java.lang.Integer. Small values (−128..127) come from the JVM's Integer cache, so you often won't see allocations in a toy demo. Push a scroll offset, an animation tick, or a timer through it and the cache stops helping.

Now the trap:

val count = mutableIntStateOf(0)

val x = count.value      // ⚠️ goes through MutableState<Int>.value → boxes
val y = count.intValue   // ✅ primitive read
var z by count           // ✅ delegate reads/writes intValue (count is a MutableIntState; an IntState-typed handle only allows `val`)

MutableIntState still is a MutableState<Int> for compatibility, so .value is available and does box. Creating the state with the right factory but reading it with .value gets you the worse of both: extra API surface and no benefit.

The same applies to mutableLongStateOf, mutableFloatStateOf, and mutableDoubleStateOf. Recent Compose versions also ship a lint check (AutoboxingStateCreation) that flags mutableStateOf with a primitive; turn it on rather than relying on code review.

Where it genuinely pays off: values written at frame rate (drag offsets, scroll position mirrors, progress). For a boolean toggled twice a minute, don’t bother.

3. SnapshotStateList: observable in place

val items = mutableStateListOf("A", "B", "C")
items.add("D")        // composables reading `items` are invalidated
items.removeAt(0)     // same
items[1] = "X"        // same

mutableStateListOf returns a SnapshotStateList<T>. Every structural change is recorded in the current snapshot, and readers (anything that iterated, indexed, or read size) are invalidated.

Compare with the alternative most people reach for first:

val items = mutableStateOf(listOf("A", "B", "C"))

// items.value.add("D")   // won't compile: List<T> has no add()
items.value = items.value + "D"   // new list, O(n) copy, new reference

Both work. They fail differently.

Which one should you use?

My default rule:

• mutableStateListOf when the list is large-ish or updated often (chat messages, form rows, selection sets) and you own the mutations in one place.
• MutableState<List<T>> (or, more commonly, a StateFlow<List<T>> in the ViewModel) when the list is produced wholesale from elsewhere, such as a repository emission, a diff result, or a sort. Replacing the reference is the natural operation.

Don’t leak mutability

class CartViewModel : ViewModel() {
    private val _items = mutableStateListOf<CartItem>()
    val items: List<CartItem> get() = _items     // callers can't add(); reads are still tracked

    fun add(item: CartItem) { _items.add(item) }
    fun remove(id: String) { _items.removeAll { it.id == id } }
}

Exposing the property as List<T> hides the mutators from callers while keeping observability, because the object behind the interface is still the SnapshotStateList. (Under strong skipping, now the default in the Kotlin 2.0.20+ Compose compiler, passing it as a List<T> parameter is fine: unstable parameters compare by instance, and the child recomposes because it reads the list.)

4. Failure modes

Here’s the code behind the four that cost the most debugging time.

4.1 The list that never updates

// ❌ Same instance, mutated. equals() is trivially true, so no invalidation.
val items = mutableStateOf(mutableListOf("A"))
items.value.add("B")

// ✅ Option 1: observable list
val items = mutableStateListOf("A")
items.add("B")

// ✅ Option 2: replace the reference
val items = mutableStateOf(listOf("A"))
items.value = items.value + "B"

Typing MutableList inside mutableStateOf is the root cause. If you catch yourself writing that, switch to mutableStateListOf.

4.2 The invisible element edit

SnapshotStateList tracks the list, not the objects inside it.

data class Task(val id: String, var done: Boolean)   // ❌ var inside a data class

val tasks = mutableStateListOf(Task("1", false))
tasks[0].done = true      // list unchanged → no recomposition

Make items immutable and replace the element, which is a tracked list write:

data class Task(val id: String, val done: Boolean)

tasks[index] = tasks[index].copy(done = true)

This also makes strong skipping and equality-based skipping behave the way you expect.

4.3 Rotation eats your list

rememberSaveable has no default saver for SnapshotStateList. If you need the list to survive configuration changes or process death at the UI layer, provide one:

@Composable
fun rememberSaveableStringList(initial: List<String> = emptyList()): SnapshotStateList<String> =
    rememberSaveable(
        saver = listSaver<SnapshotStateList<String>, String>(
            save = { it.toList() },
            restore = { it.toMutableStateList() }
        )
    ) { initial.toMutableStateList() }

In most apps, the better answer is to keep the state in a ViewModel (with SavedStateHandle for what must survive process death) and not in remember at all.

4.4 Index-based removal in a LazyColumn

// ❌ `index` was captured when this item composed. After other removals it can be stale.
LazyColumn {
    itemsIndexed(items) { index, item ->
        Row(Modifier.clickable { items.removeAt(index) }) { Text(item.title) }
    }
}

// ✅ Stable key, remove by identity
LazyColumn {
    items(items, key = { it.id }) { item ->
        Row(Modifier
            .animateItem()   // Foundation 1.7+; on older versions use animateItemPlacement() with @OptIn(ExperimentalFoundationApi::class)
            .clickable { items.removeAll { it.id == item.id } }
        ) { Text(item.title) }
    }
}

Without keys, Lazy layouts match items by position, so state like remembered text fields can jump to the wrong row after a removal. With keys, state follows the item.

4.5 Two more worth knowing

Read-modify-write races. SnapshotStateList is snapshot-safe, but this is still a lost-update bug if two coroutines run it:

state.value = state.value + newItem   // read, then write: not atomic

Fix it by funneling updates through one dispatcher, using Snapshot.withMutableSnapshot { ... } to batch related writes, or moving the source of truth to MutableStateFlow and using update { }.

Writing state during composition. Changing a state after it has already been read in the same composition is a “backwards write,” and it can cause a recomposition loop. Writes belong in event handlers and effects. If a value is a pure function of other state, derive it:

val hasItems by remember { derivedStateOf { items.isNotEmpty() } }

5. A decision guide

🔚 Closing thoughts

The mental model that prevents most of these bugs is short:

1. Compose observes reads and writes of state objects, not changes to arbitrary objects. Mutating something it can’t see changes nothing on screen.
2. Equality decides whether a write counts. Same value, no invalidation.
3. Where you read decides what reruns. Defer reads as deep as the layout allows.
4. Specialize and read through the specialized accessor. mutableIntStateOf only helps if you use .intValue.

If you only change one habit after reading this: stop putting MutableList inside mutableStateOf, and start exposing List<T> backed by a private SnapshotStateList or StateFlow.

🔐 Go Beyond Using Android — Master How It’s Actually Secured

If you’re building, testing, or breaking Android apps, understanding the security model beneath the SDK separates developers who follow best practices from those who truly understand why those practices exist. I highly recommend “Mastering Android Security: From Fundamentals to Advanced Practice.” It’s a comprehensive, architecture-first journey through app sandboxing, cryptography, network defense, reverse engineering, and exploitation — spanning everything from AndroidManifest.xml internals to TrustZone and the Verified Boot chain, with hands-on labs at every step.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover

Originally published on Medium.

This post walks through that machine: what LazyColumn composes, when, and what happens to your state when an item leaves the screen. Along the way we will pin down what key and contentType really do. A popular explanation of contentType is slightly off, and the difference matters for performance work.

Version note:LazyLayout internals (prefetch strategies, reuse policies, pausable composition) have changed between Compose releases and some remain experimental. Treat numbers such as pool sizes as implementation details and verify against the Compose version you ship.

1. The mental model: composition follows the viewport

LazyColumn does not compose every item. It composes what the current viewport needs, plus a little work done ahead of time.

Four populations of items exist at any moment:

1. Visible items are composed, measured, and placed during the measure pass. How many there are depends on the viewport size, the actual (often variable) item sizes, content padding, spacing, and partially visible edge items. It does not depend on list.size.
2. A prefetched item is composed ahead of time, in the scroll direction, using idle time in the frame. If it is not ready when the next frame needs it, the layout composes it synchronously during measure, and that is where jank comes from.
3. Recently departed items are not necessarily destroyed. Their composition slots may be retained in a reuse pool, bucketed by contentType.
4. Everything else does not exist. No composable runs, no LayoutNodes are allocated, nothing is remembered. A 10,000-item list costs roughly what a 20-item list costs.

You will often see this described as “visible items plus prefetchDistance". There is no prefetchDistance parameter on LazyColumn. Prefetching is driven by LazyListState and its prefetch strategy: by default, the next item in the scroll direction and, for a LazyRow nested in a LazyColumn, the first few items of the upcoming row. Recent Compose versions expose the strategy as an experimental API, and pausable composition lets a prefetch span frames instead of blowing one frame's budget.

2. The stack: from LazyColumn to LayoutNode

Each layer explains a behavior you will meet later:

• LazyColumn { items(...) } is only a DSL. The lambda records intervals (index ranges, each with a key, a contentType, and an item lambda) into an item provider. It does not compose anything, so never put per-item side effects in it.
• LazyListState and the measure policy own scroll position and, on every measure pass, work out which indices the incoming constraints require.
• LazyLayout is the shared foundation. LazyColumn, LazyRow, LazyVerticalGrid, LazyVerticalStaggeredGrid, and pagers are policies on top of it. It connects an item provider, a measure policy, and prefetch state.
• SubcomposeLayout is what LazyLayout is built on, and it makes laziness possible. Normal composition happens before layout. SubcomposeLayout lets measure-time code call subcompose(slotId, content), so composition can depend on layout results ("how many items fit?"). It also owns the slot pool used for reuse; LazyLayout plugs in its own reuse policy (a SubcomposeSlotReusePolicy that is aware of contentType) and wraps item content through an internal content factory.
• Composer and Applier do the real work, producing LayoutNodes that are measured and placed in the same pass.

The practical consequence: item composition happens inside the measure phase. An expensive item composable is not “slow to scroll”. It is slow to measure, and it blocks the frame.

3. Life of an item

As you scroll, every item follows the same path:

1. The measure pass decides an index is needed, because it entered the viewport or the prefetch window.
2. LazyLayout asks SubcomposeLayout for a slot. If a free slot of the same contentType exists it is reused; otherwise a new composition is created.
3. The item is measured, placed, and drawn.
4. It scrolls out of bounds.
5. Its slot goes to the reuse pool if there is room (roughly seven slots by default). If the pool is full, or no compatible item arrives, the slot is disposed.

What happens to your state

Reuse changes the answer to “is my state still there?”, which is why this trips up so many teams:

• remember { } is lost when the item is disposed, and also reset when its slot is reused for a different item. Never assume it survives a scroll.
• rememberSaveable { } is stored per key in a SaveableStateHolder and restored when the same key scrolls back in. The LazyColumn documentation asks that the key type be saveable via a Bundle on Android (String, Long, Int, a Parcelable, and so on) so the saved state can survive process death. Within a single process, the registry keeps it in memory.
• State hoisted by item id (a ViewModel or state holder) survives scrolling, reordering, and rotation. Anything a user would be upset to lose belongs here.

4. key: identity, not just state

By default an item’s identity is its index. That is fine for append-only lists and wrong for anything that reorders, inserts, or deletes.

@Immutable
sealed interface FeedItem {
    val id: Long
    val stableKey: String // unique across ALL types, saveable in a Bundle

    data class Post(override val id: Long, val title: String, val body: String) : FeedItem {
        override val stableKey: String = "post-$id" // computed once, not per read
    }
    data class Ad(override val id: Long, val sponsor: String) : FeedItem {
        override val stableKey: String = "ad-$id"
    }
    data class Story(override val id: Long, val frames: List<String>) : FeedItem {
        override val stableKey: String = "story-$id"
    }
}

A key buys you three things:

• State follows the item. rememberSaveable state is attached to the key, not the position, so a checkbox stays with its row when the list changes.
• Scroll position is anchored. LazyListState tracks the first visible item by key, so inserting items above the viewport does not shove the user's content around.
• Modifier.animateItem() works. Item animations need identity to tell "moved" from "removed and added".

Note the "post-$id" / "ad-$id" prefixes. Raw ids from different tables often collide, and a duplicate key is a hard crash, not a warning.

5. contentType: what it really does

Here is the version of the story you will find in many posts, and the correction:

• Often claimed: without contentType, every item is unique, so nothing is recycled.
• Actually true: contentType defaults to null, and null is a valid type. Items without one are all considered compatible with each other. Reuse still happens, but it happens across items whose composition structure may have nothing in common.

Reuse is only cheap when the new item has the same shape as the old one. When a slot built for an Ad receives a Story, Compose has to diff the groups, dispose the ad's nodes, and create the story's nodes. You paid for the slot bookkeeping and still got something close to a fresh composition. During a fast fling through a mixed feed, that is exactly the pattern that produces dropped frames.

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.LazyListState
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.lazy.rememberLazyListState
import androidx.compose.ui.unit.dp

@Composable
fun FeedList(
    feed: List<FeedItem>,
    modifier: Modifier = Modifier,
    state: LazyListState = rememberLazyListState(),
) {
    LazyColumn(
        modifier = modifier,
        state = state,
        contentPadding = PaddingValues(vertical = 8.dp),
        verticalArrangement = Arrangement.spacedBy(8.dp),
    ) {
        items(
            items = feed,
            key = { it.stableKey },
            contentType = { item ->
                when (item) {
                    is FeedItem.Post -> "post"
                    is FeedItem.Ad -> "ad"
                    is FeedItem.Story -> "story"
                }
            },
        ) { item ->
            when (item) {
                is FeedItem.Post -> PostCard(item)
                is FeedItem.Ad -> AdCard(item)
                is FeedItem.Story -> StoryRow(item)
            }
        }
    }
}

With this in place, a post that leaves the viewport parks its slot in the post bucket. The next post to arrive takes that slot, the node structure already matches, and only parameters that actually changed recompose.

Two rules of thumb:

• Use one contentType per distinct layout shape, not per data class. Two data classes that render the same composable can share a type, and one data class that renders two layouts (say, Post with and without media) needs two.
• Prefer cheap constants. contentType is evaluated frequently during measure. Return a string literal or enum, never something allocated per call.

Because reuse resets remember, per-item UI state must be keyed, saved, or hoisted. Reuse is not a bug that "loses" your state. It is the designed behavior that your state model has to survive.

6. Failure modes in production

Let’s expand the ones that cost the most debugging time.

6.1 State lands on the wrong row

Without a key, identity is the index. Insert one item at the top and the state that lived at index 3 now belongs to a different item.

// Bug: identity is the index
items(feed) { PostCard(it) }

// Fix: identity is the domain id
items(feed, key = { it.stableKey }) { PostCard(it) }

6.2 IllegalArgumentException: Key "…" was already used

Common with paging, where adjacent pages overlap, and with ids that are only unique per type. Deduplicate upstream and namespace keys by type, as in section 4. Do not “fix” this by appending the index to the key, since that silently reintroduces index identity.

6.3 Nested vertical scrolling

This one throws an IllegalStateException (not the IllegalArgumentException of duplicate keys):

// Crash: "Vertically scrollable component was measured with an infinity maximum height"
Column(Modifier.verticalScroll(rememberScrollState())) {
    Header()
    LazyColumn { items(feed) { PostCard(it) } }
}

A lazy list needs a bounded height to know what fits. Put the header inside the list instead:

LazyColumn {
    item(key = "header", contentType = "header") { Header() }
    items(feed, key = { it.stableKey }, contentType = { "post" }) { PostCard(it) }
    item(key = "footer", contentType = "footer") { Footer() }
}

6.4 UI state that resets on scroll

Expanded cards and half-typed text are classic victims. Scroll away, scroll back, and they are gone.

// Resets whenever the slot is disposed or reused
var expanded by remember { mutableStateOf(false) }

// Survives scrolling and process death, given a stable key on the item
var expanded by rememberSaveable { mutableStateOf(false) }

For anything more valuable than a toggle, hoist by id:

class FeedViewModel : ViewModel() {
    private val _expanded = MutableStateFlow<Set<String>>(emptySet())
    val expanded: StateFlow<Set<String>> = _expanded

    fun toggle(key: String) = _expanded.update { if (key in it) it - key else it + key }
}

6.5 Reading scroll state in composition

// Bug: recomposes the whole parent each time the first visible index changes
val showButton = state.firstVisibleItemIndex > 3

// Fix: only recompose when the boolean actually flips
val showButton by remember {
    derivedStateOf { state.firstVisibleItemIndex > 3 }
}

To be precise, firstVisibleItemIndex changes only when the first visible item changes, so intra-item pixel scrolling (firstVisibleItemScrollOffset) does not trigger it. In a fast fling it still changes many times per second, and every change recomposes the parent for no visible effect.

The same applies to infinite scrolling. Do it as a side effect, not a composition read:

LaunchedEffect(state) {
    snapshotFlow {
        val last = state.layoutInfo.visibleItemsInfo.lastOrNull()?.index ?: -1
        last >= state.layoutInfo.totalItemsCount - 5
    }
        .distinctUntilChanged()
        .filter { it }
        .collect { onLoadMore() }
}

The snapshotFlow block re-runs whenever layoutInfo changes, but distinctUntilChanged() ensures downstream code only sees the boolean flipping, and nothing recomposes.

6.6 Unstable parameters defeating skipping

Item composables can only skip recomposition when their inputs are stable and equal. A List<String> parameter on a non-strong-skipping setup, or a lambda recreated on every parent recomposition, forces every visible item to recompose. Prefer immutable models, @Immutable/@Stable where honest, kotlinx.collections.immutable for collections, and lambdas that capture stable values such as the item id.

7. A checklist before you ship a feed

• Every items block has a stable, unique, type-namespaced key.
• Every items block has a contentType per distinct layout shape, as cheap constants.
• No per-item UI state lives in plain remember unless losing it is acceptable.
• Scroll-derived UI uses derivedStateOf or snapshotFlow, not direct reads in composition.
• No lazy list sits inside an unbounded vertical scroll container.
• You have profiled a fast fling on a mid-range device in a release build, with R8 and baseline profiles. Debug builds exaggerate lazy-list jank considerably.

🔚 Takeaways

• LazyColumn composes the viewport plus a prefetched item, and does so inside the measure pass.
• Slots left behind are pooled by contentType, not destroyed immediately, and reuse resets remember.
• key gives items identity. contentType gives slots compatibility. Without contentType, reuse still happens, just between items that may not match, which costs you most of its benefit.
• Most production bugs here are not Compose bugs. They are state models that quietly assumed items live forever.

📱 Go Beyond Using AI — Learn How to Actually Build It Into Your Android Apps

If you’re building Android apps in 2026, “adding AI” can’t just mean bolting on a chatbot API — it means understanding on-device inference, model trade-offs, and production realities well enough to ship a feature users actually trust. I highly recommend “Mastering Android AI: App to Intelligence” It’s a practical, code-first journey through the entire Android AI stack — from ML Kit and LiteRT to Gemma, Gemini, and MediaPipe — covering everything from your first “hello inference” screen to thermal throttling, model drift monitoring, and full applied projects like an AI-powered camera app and a health companion, with hands-on Kotlin builds at every step.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover

Originally published on Medium.

This post covers what the slot table is, how recomposition walks it, and the failure modes you will hit in production.

What the slot table is

The slot table is Compose’s runtime record of your composition. Where the View system gives you a tree of heap objects, Compose gives you a linear, array-backed structure that is read and written in the same order your composable functions execute.

Take this code:

@Composable
fun Screen() {
    Column {
        Text("Hello")
        val counter = remember { mutableStateOf(0) }
        Text("World")
    }
}

The mental model is a flat sequence of groups and data:

Nesting is encoded by position and group size, not by parent pointers you chase at runtime. That is what makes the walk cheap and cache-friendly.

The mental model is slightly wrong (on purpose)

The single-array picture is the right way to think, but the real SlotTable in androidx.compose.runtime splits the data across two parallel arrays:

• groups: IntArray: a fixed number of ints per group (key, flags and node count, parent anchor, size, data anchor).
• slots: Array<Any?>: the payload: remembered values, recompose scopes, previous values of non-constant parameters (for skipping checks), nodes, and so on.

One correction to the simplified picture above: "Hello" and "World" are compile-time constants. The compiler marks such arguments as static in $changed, so they are not stored in a slot. A parameter that varies at runtime, such as Text(name), is stored so the next recomposition can compare it. The linear diagram is a teaching model; group descriptors and slot payloads actually live in separate address spaces.

Both are gap buffers. Details change between runtime versions, so treat the field layout as illustrative rather than as an API.

Why gap buffers? Composition is mostly “edit near where I last edited”. A gap buffer keeps a hole at the last edit point, so insertions and removals there are close to free. A distant edit costs one array copy to move the gap.

Where the keys come from

You never write group keys. The Compose compiler plugin rewrites each composable to take an extra Composer and a $changed bitmask, and it wraps bodies in group calls with an Int key derived from the source location. Conceptually, Screen becomes:

// Conceptual output. Do not rely on exact shape.
fun Screen(composer: Composer, changed: Int) {
    composer.startRestartGroup(/* key = 0x1A2B... */)
    // body, with startReplaceGroup/startMovableGroup around
    // conditionals, loops, and key { } blocks
    composer.endRestartGroup()?.updateScope { c, _ -> Screen(c, changed or 1) }
}

Three group flavors matter in practice:

• Restart groups wrap composables that return Unit. They are the unit of recomposition scope.
• Replaceable groups wrap branches (if/when). A different branch means a different key, so old slots are discarded.
• Movable groups come from key(x) { }. They carry an object key, so the runtime can find and move a group instead of destroying it.

How recomposition walks the table

During recomposition the composer keeps a cursor into the table and does not rebuild the tree. At each group it asks:

In words:

1. Same key, inputs unchanged: skip. The cursor jumps past the group using its recorded size, so none of its children run.
2. Same key, inputs changed: re-run the body, reusing the slots already stored for children.
3. Different key: look for a movable group with that key. If found, move it and keep its state. Otherwise, insert a new group, run the code, and remove the old slots.
4. remember slot: compare the remember keys. Unchanged returns the cached value without running your lambda.

Skipping depends on the compiler comparing each parameter to the value stored in the slot table from the last composition. Stable types are compared with equals. Since Kotlin 2.0.20, strong skipping mode is on by default and also skips with unstable parameters, comparing them by instance (===). Check your compiler version before reasoning about why something did or did not skip.

Position is identity

Here is the sentence that explains most state bugs: the position in the slot table is the identity. Two remember {} calls at different positions get different slots, because they are different call sites in execution order.

That is also the failure mode.

Failure mode 1: Loops without keys

@Composable
fun ExpandableList(items: List<Item>) {
    Column {
        items.forEach { item ->
            // BUG: identity is the loop iteration order, not item.id
            var expanded by remember { mutableStateOf(false) }
            ItemRow(item, expanded) { expanded = !expanded }
        }
    }
}

The user expands B, then deletes A. Slot 0 still holds false, slot 1 still holds true:

Fix it by giving each iteration a stable identity:

@Composable
fun ExpandableList(items: List<Item>) {
    Column {
        items.forEach { item ->
            key(item.id) {
                var expanded by remember { mutableStateOf(false) }
                ItemRow(item, expanded) { expanded = !expanded }
            }
        }
    }
}

I kept plain remember so the only change is key(item.id). If the expanded state must also survive recreation or process death, swap in rememberSaveable. Its default key already incorporates the enclosing key(item.id) group, so no extra key is needed, but the value must be Bundle-saveable.

In lazy lists, the equivalent is items(items, key = { it.id }). Make sure keys are unique and stable. Duplicate keys crash LazyColumn at runtime, and key {} with duplicates silently produces ambiguous matching.

Failure mode 2: Keys that are not really keys

key(index) or key(item.hashCode()) on mutable data defeats the purpose. Index is just position again, and a hash that changes when the item mutates will tear down state on every edit. Use a stable domain ID.

Failure mode 3: Conditional branches silently reset state

@Composable
fun Profile(isEditing: Boolean, user: User) {
    if (isEditing) {
        var draft by remember { mutableStateOf(user.name) }
        EditForm(draft) { draft = it }
    } else {
        ReadOnlyForm(user)
    }
}

Each branch has its own group, so leaving the isEditing branch discards draft. Often that is what you want; the bug is expecting it to survive. If state must outlive the branch, hoist it above the if, or store it in a ViewModel or rememberSaveable higher up.

Failure mode 4: remember with the wrong keys

@Composable
fun UserBadge(userId: String, repo: UserRepo) {
    // BUG: stale if userId changes; the slot already holds a value
    val user = remember { repo.cachedUser(userId) }

    // Correct: re-run when the input changes
    val fresh = remember(userId) { repo.cachedUser(userId) }
}

Without keys, the lambda runs once for the group’s lifetime. Pass every input the lambda captures as a key.

Failure mode 5: Stale lambdas captured by long-lived effects

@Composable
fun Timer(onTimeout: () -> Unit) {
    // BUG: effect captures the first onTimeout forever
    LaunchedEffect(Unit) {
        delay(5_000)
        onTimeout()
    }
}

@Composable
fun TimerFixed(onTimeout: () -> Unit) {
    val currentOnTimeout by rememberUpdatedState(onTimeout)
    LaunchedEffect(Unit) {
        delay(5_000)
        currentOnTimeout()
    }
}

rememberUpdatedState keeps one slot whose value is refreshed each recomposition, so the long-lived coroutine always reads the latest lambda.

Failure mode 6: Remembered objects leak what they capture

Slots hold strong references until their group leaves the composition. Remembering something that captures an Activity or a large Bitmap ties its lifetime to that group. For resources with cleanup, implement RememberObserver (or use DisposableEffect) so onForgotten runs when the slot is dropped.

// Common pattern: fine for normal lifecycles
@Composable
fun rememberPlayer(context: Context): ExoPlayer {
    val appContext = context.applicationContext
    val player = remember { ExoPlayer.Builder(appContext).build() }
    DisposableEffect(player) { onDispose { player.release() } }
    return player
}

This has a gap. If composition is abandoned after remember runs but before the changes are applied (for example, a cancelled or interrupted composition), the DisposableEffect never enters, so onDispose never runs and the player leaks. Wrapping the resource in a RememberObserver covers forgotten and abandoned slots:

private class PlayerHolder(context: Context) : RememberObserver {
    val player: ExoPlayer = ExoPlayer.Builder(context).build()

    override fun onRemembered() = Unit
    override fun onForgotten() = player.release()
    override fun onAbandoned() = player.release()
}

@Composable
fun rememberPlayer(context: Context): ExoPlayer {
    val appContext = context.applicationContext
    return remember { PlayerHolder(appContext) }.player
}

Failure mode 7: Expecting remember to survive recreation

The slot table belongs to the composition. When the Activity is recreated on a configuration change, the composition is rebuilt and every remember slot starts empty. Use rememberSaveable for small UI state, and a ViewModel for anything heavy or asynchronous.

Failure mode 8: Side effects during composition

Composition can run more than once, be abandoned, or run in a different order than you expect. Writing to state or doing I/O in the body is how you get infinite recomposition loops and flaky tests:

@Composable
fun Bad(vm: VM) {
    vm.track("screen_shown")   // runs on every recomposition
}

@Composable
fun Good(vm: VM) {
    LaunchedEffect(Unit) { vm.track("screen_shown") }
}

Debugging checklist

• Layout Inspector recomposition counts show which composables run and which are skipped.
• Suspect state loss? Look for a branch, a loop, or a movableContentOf boundary above the remember.
• Suspect missed skipping? Check parameter stability and the Compose compiler reports (-P plugin:androidx.compose.compiler.plugins.kotlin:reportsDestination=...).
• Reordering a collection? Every item needs a stable key.

Takeaways

• The slot table stores the composition as groups and data in a linear, gap-buffered structure; the real implementation uses parallel arrays, and constants are not stored in slots.
• Recomposition is a cursor walk: matching keys are skipped or re-run, mismatched keys move or replace.
• Position is identity. remember is scoped to a call site in execution order, so keys, branches, and loops determine whether your state survives.
• Most “Compose bugs” are identity bugs: add key(), hoist state, or key your remember.

📱 New to Jetpack Compose? Start Here

If you’re coming from the classic Android View system — XML layouts, findViewById, RecyclerView adapters — and want a clear, no-jargon path into Jetpack Compose, I recommend "Learning Jetpack Compose: Your Practical Guide from the Android View System to Modern Declarative UI." Every chapter starts from something you already know and shows its Compose equivalent side by side, building up to a full capstone: a real Notes app. Once you're comfortable and want to go deeper — the Composition tree, recomposition internals, the runtime itself — "Mastering Jetpack Compose Internals" is the natural next step.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover

Originally published on Medium.

@Composable
fun Conditional(showA: Boolean) {
    Column {
        if (showA) {
            ComponentA()   // owns remember { } state
        } else {
            ComponentB()   // owns remember { } state
        }
    }
}

When showA flips from true to false, ComponentA is not hidden. It is disposed. Every remember, every LaunchedEffect, every DisposableEffect inside it is torn down, and ComponentB is composed from scratch with initial state.

This post covers why, the failure modes that bite in production, and the five tools you actually have for controlling it.

The mental model: hidden means deleted

In the View system, visibility = GONE keeps the node in the tree. The object, its fields, and its listeners all survive. Compose inverts that: the composition describes what exists right now, and anything not described is gone.

What actually happens at the slot table

The Compose compiler wraps each branch of a conditional in its own replace group, keyed by call site. Recomposition after showA flips goes like this:

1. The Column group is still there, so it is reused.
2. The group for the if branch no longer matches the group the runtime expects at that position. The runtime sees a different key and treats it as a different node, not as an update.
3. The old group (and everything nested under it) is removed from the slot table. Each RememberObserver receives onForgotten(), DisposableEffects run onDispose, and LaunchedEffect coroutines are cancelled.
4. The else group is inserted and its remember blocks run their initializers.

One detail that surprises people: this is keyed by call site, not by composable function. Calling the same composable from both branches still resets state, because each branch is a distinct group:

// Looks like "the same Player", but state resets on every flip.
if (isCompact) {
    Player(modifier = Modifier.fillMaxWidth())
} else {
    Player(modifier = Modifier.size(320.dp))
}

Failure modes you will meet in production

1. Scroll position and text drafts vanish. rememberLazyListState() and rememberTextFieldState() are backed by rememberSaveable, but that only protects them from configuration change and process death. A branch swap disposes their entries in a live process, so the user is back at the top with an empty field. A plain remember { TextFieldState() } or remember { mutableStateOf("") } fails the same way, just with less protection.

2. Effects re-fire and double your network traffic. Flipping back re-enters the branch, so LaunchedEffect(Unit) { repository.load() } runs again. Rapid toggling produces a burst of cancelled and restarted requests, plus loading spinners that flash on every flip.

3. Heavy resources are rebuilt. An ExoPlayer created in remember and released in onDispose is released and recreated each time. Users hear audio restart; you see MediaCodec init cost in traces.

4. rememberSaveable does not save you here. It survives configuration change and process death, but a branch swap within a live process disposes its entry. People assume "saveable" means "survives anything". It does not.

5. AnimatedVisibility is not a state preserver. This is the most common wrong fix. AnimatedVisibility plays the exit transition and then removes the content from composition. After the exit finishes, remember state is gone, same as if. It is a visual transition, not a lifetime extension.

// Does NOT preserve ComponentA's remember state after the exit animation ends.
AnimatedVisibility(visible = showA) {
    ComponentA()
}

6. Passing a different key() resets by design. key() is often described as a way to preserve state. It does the opposite: a different key means a different identity, hence fresh state. It is a tool for forcing a reset, or for keeping identity stable when position changes (reordering list items).

What survives what

The pattern is clear: if the state lives inside the subtree, anything that removes the subtree removes the state. To keep it, either move the state out, or stop removing the subtree.

The toolbox

1. Hoist the state (default choice)

State that must outlive visibility does not belong inside the thing that gets hidden. Lift it to a state holder owned by a stable parent:

@Stable
class ListPaneState(
    initialQuery: String = "",
    firstVisibleItemIndex: Int = 0,
    firstVisibleItemScrollOffset: Int = 0,
) {
    var query by mutableStateOf(initialQuery)
    val listState = LazyListState(firstVisibleItemIndex, firstVisibleItemScrollOffset)

    companion object {
        // Constructing LazyListState directly is fine, but nothing persists it
        // unless you save index and offset yourself.
        val Saver: Saver<ListPaneState, Any> = listSaver(
            save = {
                listOf(
                    it.query,
                    it.listState.firstVisibleItemIndex,
                    it.listState.firstVisibleItemScrollOffset,
                )
            },
            restore = { ListPaneState(it[0] as String, it[1] as Int, it[2] as Int) },
        )
    }
}

@Composable
fun rememberListPaneState(): ListPaneState =
    rememberSaveable(saver = ListPaneState.Saver) { ListPaneState() }

@Composable
fun Conditional(showA: Boolean) {
    val paneState = rememberListPaneState() // lives in the parent, outlives the branch
    Column {
        if (showA) ComponentA(paneState) else ComponentB()
    }
}

For anything that must survive configuration change, put it in a ViewModel and expose it as StateFlow collected with collectAsStateWithLifecycle(). This is also what makes the UI trivially testable.

2. SaveableStateProvider for tabs and switchers

If the content is “one of N screens” and each screen owns its own rememberSaveable state, give each a keyed saveable registry. This is what Navigation Compose does per back-stack entry:

@Composable
fun <K : Any> KeyedSwitcher(
    current: K,          // must be saveable: String, Int, enum name, Parcelable...
    liveKeys: Set<K>,    // every key that can still be navigated to; must contain `current`
    modifier: Modifier = Modifier,
    content: @Composable (K) -> Unit,
) {
    val holder = rememberSaveableStateHolder()
    val seen = remember { mutableSetOf<K>() }

    // Without this, saved state for dead keys accumulates for the whole session.
    LaunchedEffect(current, liveKeys) {
        seen += current
        (seen - liveKeys).forEach { holder.removeState(it) }
        seen.retainAll(liveKeys)
    }

    Box(modifier) {
        holder.SaveableStateProvider(key = current) {
            content(current)
        }
    }
}

Each key’s rememberSaveable values are stashed when that content leaves composition and restored when it returns. Plain remember is still lost, so use rememberSaveable inside the content. Two operational notes:

• Cleanup is your job. The holder never evicts anything on its own. For dynamic keys (a tab per open document, say), wire removeState(key) to the moment a key is truly gone, as above. Skipping this is a slow leak that only shows up in long sessions.
• The holder’s lifetime is the switcher’s lifetime. It is created with rememberSaveableStateHolder(), so if KeyedSwitcher itself leaves composition, the stashed entries go with it. Place the switcher above whatever boundary you need to survive, or hoist the holder.

3. Keep it composed, but not drawn

When the subtree is expensive to rebuild and you must keep everything (animations, scroll, player), keep it in composition and skip placement:

/**
 * Keeps the subtree composed (state and effects alive) but invisible and inert.
 * collapse = false behaves like View.INVISIBLE: the space stays reserved.
 * collapse = true behaves like View.GONE: the subtree takes 0x0.
 */
fun Modifier.hidden(hidden: Boolean, collapse: Boolean = false): Modifier =
    if (!hidden) this else this
        .layout { measurable, constraints ->
            val placeable = measurable.measure(constraints)
            val w = if (collapse) 0 else placeable.width
            val h = if (collapse) 0 else placeable.height
            // Measured but never placed: nothing is drawn, nothing is hit-tested.
            layout(w, h) {}
        }
        .clearAndSetSemantics {} // defensive: keep TalkBack out of the hidden subtree

@Composable
fun Conditional(showA: Boolean) {
    Column {
        // collapse = true, otherwise the hidden one leaves a blank gap in the Column.
        ComponentA(Modifier.hidden(hidden = !showA, collapse = true))
        ComponentB(Modifier.hidden(hidden = showA, collapse = true))
    }
}

Pick the collapse mode deliberately. The default reserves space, which is right for toggling something in place, and wrong for a swap, where it leaves a blank hole.

The trade-off is real: a hidden subtree still composes, still measures, and its LaunchedEffects keep running. A polling loop or a Lottie animation inside it keeps burning battery. Pair it with a visible parameter that your effects respect:

LaunchedEffect(visible) {
    if (visible) feed.collect { /* ... */ }
}

Avoid Modifier.alpha(0f) as the whole solution: it still lays out and, depending on version and parent, can remain reachable by touch and by accessibility services. Verify with TalkBack before shipping.

4. movableContentOf when the same content changes parent

For the “same Player, different container” case, a branch swap loses state but moving content preserves it:

@Composable
fun AdaptivePlayer(isWide: Boolean, url: String) {
    val player = remember(url) {
        movableContentOf { Player(url) }
    }
    if (isWide) {
        Row { player() }
    } else {
        Column { player() }
    }
}

remember state inside Player follows it between the Row and the Column. This only applies when the content is moved; if it is absent from both parents for a frame, it is disposed.

5. key() to reset on purpose

When you want the opposite, such as clearing a form when the selected entity changes, use key:

key(userId) {
    ProfileEditor(userId) // new userId = new identity = fresh state
}

This is the correct replacement for hand-written “reset on id change” LaunchedEffect logic.

Proving it: a test that guards the behavior

Do not trust your memory of this. Encode it:

@Composable
fun Counter(tag: String) {
    var count by remember { mutableIntStateOf(0) }
    Text(
        text = count.toString(),
        modifier = Modifier.testTag(tag).clickable { count++ },
    )
}

class ConditionalStateTest {
    @get:Rule val rule = createComposeRule() // androidx.compose.ui.test.junit4

    @Test
    fun counterResetsWhenBranchSwaps() {
        val showA = mutableStateOf(true)
        rule.setContent {
            if (showA.value) Counter(tag = "a") else Counter(tag = "b")
        }

        rule.onNodeWithTag("a").performClick()
        rule.onNodeWithTag("a").assertTextEquals("1")

        rule.runOnIdle { showA.value = false }
        rule.onNodeWithTag("b").assertTextEquals("0")

        rule.runOnIdle { showA.value = true }
        rule.onNodeWithTag("a").assertTextEquals("0") // state was lost
    }
}

This needs androidx.compose.ui:ui-test-junit4 as an androidTestImplementation (or testImplementation with Robolectric) and ui-test-manifest as debugImplementation.

For quick debugging, drop a lifecycle probe into the suspect composable. Seeing onDispose fire on every toggle ends the argument immediately:

@Composable
fun LifecycleProbe(name: String) {
    DisposableEffect(Unit) {
        Log.d("Probe", "$name entered composition")
        onDispose { Log.d("Probe", "$name left composition") }
    }
}

Rules of thumb

• Treat every if that gates a composable as a lifetime boundary, not a visibility switch.
• State that must outlive a boundary lives above it: a hoisted holder, a ViewModel, or a SaveableStateProvider.
• AnimatedVisibility animates the boundary; it does not remove it.
• Keeping content composed is a performance decision, not a free lunch. Gate its effects.
• Reach for key() to reset, movableContentOf to relocate, and neither to preserve across hiding.

The View-era instinct says “hide it and the state will be fine”. In Compose, the question to ask is different: who owns this state, and does that owner outlive the branch?

📱 Go Beyond Using Jetpack Compose

If you’re building on Android, understanding what happens under the hood separates developers who use Compose from those who master it. I highly recommend “Mastering Jetpack Compose Internals”. It’s a deep, architecture-first walkthrough of the composition tree, the slot table, snapshot state, and the runtime that powers modern Android UI — capped off with a full case study building a real app called Mosaic.

• E-book: Available on Google Play
• Kindle Edition: Available on Amazon
• Topmate: Available on Topmate
• Also available in Paperback & Hardcover

Originally published on Medium.