DEV Community: SuriDevs

My Compose App Was Showing the Wrong Theme After Restart — Here's the Fix

SuriDevs — Mon, 11 May 2026 04:51:19 +0000

A user reported that the app kept resetting to light mode on every restart even though they'd set it to dark.

The bug was embarrassingly simple: I was only updating a StateFlow. The ViewModel emitted the new theme, Compose recomposed, everything looked correct — until the process died. On the next cold start, the MutableStateFlow initialised with a hardcoded default and the persisted preference was never read.

That's the most common Compose dark mode bug. This post covers the full production pattern that prevents it.

Start With an Enum, Not a Boolean

A Boolean gives you light or dark. Users need a third option: follow the system.

enum class ThemeMode(val value: Int) {
    LIGHT(0), DARK(1), SYSTEM(2)
}

SYSTEM as the default (value = 2) is the right out-of-the-box experience. Storing .value as an Int keeps SharedPreferences simple.

Persist With SharedPreferences

object ThemePreferences {
    private const val PREFS_NAME = "com.example.theme_prefs"
    private const val KEY = "theme_mode"
    private const val DEFAULT = ThemeMode.SYSTEM.value

    private fun prefs() = App.context
        .getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)

    var theme: Int
        get() = prefs().getInt(KEY, DEFAULT)
        set(value) { prefs().edit().putInt(KEY, value).apply() }
}

Don't use PreferenceManager.getDefaultSharedPreferences() — it's deprecated in the AndroidX Preference library. Call getSharedPreferences() directly.

Don't reach for DataStore either. Its async read means you need a splash or loading state to avoid a first-frame flicker. SharedPreferences' synchronous getInt() completes before the first frame — exactly what you want for a theme preference.

ThemeViewModel: Two Writes, Not One

class ThemeViewModel : ViewModel() {

    private val _themeMode = MutableStateFlow(
        ThemeMode.entries.first { it.value == ThemePreferences.theme }
    )
    val themeMode: StateFlow<ThemeMode> = _themeMode.asStateFlow()

    fun setTheme(mode: ThemeMode) {
        ThemePreferences.theme = mode.value  // survives process death
        _themeMode.value = mode              // drives recomposition now
    }
}

This is where most tutorials stop — they emit to the StateFlow and call it done. Without the SharedPreferences write, the theme resets on every cold start.

AppCompatDelegate is intentionally absent here. It belongs in the Activity, not the ViewModel. More on that in a moment.

AppTheme: Resolve the Boolean, Build the Scheme

@Composable
fun AppTheme(
    themeMode: ThemeMode,
    content: @Composable () -> Unit
) {
    val darkTheme = when (themeMode) {
        ThemeMode.LIGHT  -> false
        ThemeMode.DARK   -> true
        ThemeMode.SYSTEM -> isSystemInDarkTheme()
    }

    val customColors = if (darkTheme) DarkAppColors else LightAppColors

    val colorScheme = if (darkTheme) {
        darkColorScheme(
            primary    = Color(0xFF2C3638),
            secondary  = Color(0xFFBDBDBD),
            background = Color(0xFF1E1F25),
            surface    = Color(0xFF1E1F25),
            onPrimary  = Color.White,
            error      = Color(0xFFB00020),
        )
    } else {
        lightColorScheme(
            primary    = Color(0xFFFBFBFB),
            secondary  = Color(0xFF276EF7),
            background = Color(0xFFFBFBFB),
            surface    = Color(0xFFFBFBFB),
            onPrimary  = Color.Black,
            error      = Color(0xFFB00020),
        )
    }

    MaterialTheme(colorScheme = colorScheme) {
        CompositionLocalProvider(
            LocalCustomColors provides customColors,
            LocalIsDarkTheme provides darkTheme,
        ) {
            content()
        }
    }
}

Use darkColorScheme() / lightColorScheme() — not the ColorScheme(...) constructor directly. The factory functions supply safe defaults for all 30 M3 roles; the constructor requires every single role to be explicitly set or it won't compile.

isSystemInDarkTheme() is Compose-aware — reading it inside a composable automatically triggers recomposition when the system mode changes. No manual observer needed.

Why Two Color Systems? (The Part Most Tutorials Skip)

M3 gives you 30 color roles. If your app has more than 30 semantic colors — cardBackgroundColor, dividerColor, inputFieldBorderColor, sectionHeaderColor, and so on — you have two bad options:

Overload M3 roles: now surface means three different things in different contexts.
Nest MaterialTheme at the component level: causes unnecessary recomposition and makes the theme graph confusing.

The right answer is a second color system via CompositionLocal:

data class AppColors(
    val colorPrimary: Color,
    val backgroundColor: Color,
    val cardBackgroundColor: Color,
    val dividerColor: Color,
    val primaryTextColor: Color,
    val sectionHeaderColor: Color,
    // ...
)

val LightAppColors = AppColors(
    colorPrimary       = Color(0xFF276EF7),
    backgroundColor    = Color(0xFFFBFBFB),
    cardBackgroundColor= Color(0xFFFFFFFF),
    dividerColor       = Color(0xFFE0E0E0),
    primaryTextColor   = Color(0xFF212121),
    sectionHeaderColor = Color(0xFF757575),
)

val DarkAppColors = AppColors(
    colorPrimary       = Color(0xFFBDBDBD),
    backgroundColor    = Color(0xFF1E1F25),
    cardBackgroundColor= Color(0xFF2C3638),
    dividerColor       = Color(0xFF3A3A3A),
    primaryTextColor   = Color(0xFFEEEEEE),
    sectionHeaderColor = Color(0xFF9E9E9E),
)

val LocalCustomColors = staticCompositionLocalOf { LightAppColors }
val LocalIsDarkTheme  = staticCompositionLocalOf { false }

Use staticCompositionLocalOf — not compositionLocalOf. For a root-level theme that changes rarely, staticCompositionLocalOf invalidates the entire subtree on change (correct for a full theme swap) and has lower per-frame overhead since there's no per-consumer tracking.

Expose the colors through a single access object:

object AppThemeColor {
    val colors: AppColors
        @Composable
        @ReadOnlyComposable
        get() = LocalCustomColors.current
}

Screens call AppThemeColor.colors.cardBackgroundColor instead of MaterialTheme.colorScheme.surface. Clean semantics, no ambiguity, and M3 components still get their roles via the partial ColorScheme mapping.

MainActivity: Where AppCompatDelegate Lives

If your app has any XML-based Activities or dialogs, AppCompatDelegate.setDefaultNightMode() must stay in sync with the theme. It belongs in the Activity reacting to the StateFlow — not in the ViewModel (wrong layer, threading risk).

class MainActivity : AppCompatActivity() {

    private val themeViewModel: ThemeViewModel by viewModels()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        lifecycleScope.launch {
            themeViewModel.themeMode.collect { mode ->
                AppCompatDelegate.setDefaultNightMode(
                    when (mode) {
                        ThemeMode.LIGHT  -> AppCompatDelegate.MODE_NIGHT_NO
                        ThemeMode.DARK   -> AppCompatDelegate.MODE_NIGHT_YES
                        ThemeMode.SYSTEM -> AppCompatDelegate.MODE_NIGHT_FOLLOW_SYSTEM
                    }
                )
            }
        }

        setContent {
            val themeMode by themeViewModel.themeMode.collectAsStateWithLifecycle()

            AppTheme(themeMode = themeMode) {
                AppNavigation(themeViewModel = themeViewModel)
            }
        }
    }
}

collectAsStateWithLifecycle() requires androidx.lifecycle:lifecycle-runtime-compose — add it if it's not already in your dependencies.

Critical: the lifecycleScope collector runs after the first frame. To avoid a flicker on cold start, restore AppCompatDelegate in Application.onCreate() synchronously:

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        AppCompatDelegate.setDefaultNightMode(
            when (ThemeMode.entries.first { it.value == ThemePreferences.theme }) {
                ThemeMode.LIGHT  -> AppCompatDelegate.MODE_NIGHT_NO
                ThemeMode.DARK   -> AppCompatDelegate.MODE_NIGHT_YES
                ThemeMode.SYSTEM -> AppCompatDelegate.MODE_NIGHT_FOLLOW_SYSTEM
            }
        )
    }
}

The Settings Toggle

@Composable
fun ThemeSettingsSection(
    currentTheme: ThemeMode,
    onThemeSelected: (ThemeMode) -> Unit
) {
    val options = listOf(
        ThemeMode.LIGHT  to "Light",
        ThemeMode.DARK   to "Dark",
        ThemeMode.SYSTEM to "System default"
    )

    Column {
        Text(
            text = "App theme",
            style = MaterialTheme.typography.labelLarge,
            color = AppThemeColor.colors.sectionHeaderColor
        )
        Spacer(modifier = Modifier.height(8.dp))
        options.forEach { (mode, label) ->
            Row(
                modifier = Modifier
                    .fillMaxWidth()
                    .clickable { onThemeSelected(mode) }
                    .padding(vertical = 12.dp, horizontal = 16.dp),
                verticalAlignment = Alignment.CenterVertically
            ) {
                RadioButton(selected = currentTheme == mode, onClick = { onThemeSelected(mode) })
                Spacer(modifier = Modifier.width(12.dp))
                Text(text = label, color = AppThemeColor.colors.primaryTextColor)
            }
        }
    }
}

For conditional values outside AppThemeColor — like an icon tint — read LocalIsDarkTheme.current instead of calling back into the ViewModel:

val isDark = LocalIsDarkTheme.current
val iconTint = if (isDark) Color.White else Color.Black

Mistakes That Bite in Production

Only emitting to StateFlow. Without the SharedPreferences write, the theme resets on every cold start. This is the original bug.

Putting AppCompatDelegate in the ViewModel. It must run on the main thread. The lifecycleScope collector guarantees that. A ViewModel function can be called from coroutines on any dispatcher.

Skipping the Application.onCreate() startup call. The lifecycleScope collector fires after the first frame. Without the startup call, Activities briefly flash the wrong theme before the collector updates it.

Caching the isSystemInDarkTheme() result. It's a Compose state read — it must be called inside the composition. Cache it outside and you'll miss system mode changes.

FAQ

Does this work on Android below API 29?

isSystemInDarkTheme() returns false on API 28 and below — those versions don't support system dark mode. ThemeMode.SYSTEM effectively behaves like ThemeMode.LIGHT on pre-Q devices. Users can always manually select DARK from Settings.

Do I need to add android:configChanges="uiMode"?

No — for most apps, omit it. Without that flag, the system recreates XML Activities automatically on a uiMode change, which is correct. Adding it suppresses recreation and forces you to handle onConfigurationChanged() yourself.

How do I preview both themes in Android Studio?

@Preview(name = "Dark", uiMode = Configuration.UI_MODE_NIGHT_YES)
@Preview(name = "Light", uiMode = Configuration.UI_MODE_NIGHT_NO)
@Composable
fun MyScreenPreview() {
    AppTheme(themeMode = ThemeMode.DARK) { MyScreen() }
}

ThemeMode is a plain enum — no fake ViewModel needed in previews.

Originally published at suridevs.com

My Camera App Was Crashing When Users Mixed HDR + 60 FPS — CameraX Fixed It

SuriDevs — Sat, 09 May 2026 09:31:29 +0000

A user filed a crash report. Their phone supported HDR. It supported 60 FPS. I'd tested both features separately and they worked fine. But the moment they enabled both together, the camera session died with an IllegalStateException buried somewhere deep in the camera HAL.

I couldn't reproduce it — my Pixel handled the combo just fine. Their mid-range device did not.

That's the kind of bug that follows you. You add a device to the "doesn't support X+Y" list in your code. Another device shows up a month later. The list grows. Nobody is happy.

CameraX's Feature Groups API is the answer to this. You query whether a combination of features works before you try to enable it. No list-keeping. No trial and error. No crashes.

The Old Way Was Just Guessing

Previously you'd enable features one at a time and hope for the best:

// Old approach - optimism as a strategy
videoCapture.apply {
    setHdr(true)
    setTargetFrameRate(Range(60, 60))
    setStabilization(true)
}
// Might work. Might crash. Might silently fail. Fun times.

Some devices support HDR. Some support 60 FPS. Some support HDR + 60 FPS together. Others have the hardware for both individually but the camera HAL can't run them simultaneously. The only way to know was to test — or let users find out the hard way.

How Feature Groups Actually Work

You ask the device: can you do these things at the same time?

val features = setOf(
    GroupableFeature.HDR_HLG10,
    GroupableFeature.FPS_60,
    GroupableFeature.PREVIEW_STABILIZATION
)

if (cameraInfo.isFeatureGroupSupported(features)) {
    // All three work together — safe to proceed
} else {
    // Need to fall back to something the device can handle
}

Or you can hand CameraX a wish list and let it find the best supported subset automatically:

cameraProvider.bindToLifecycle(
    lifecycleOwner,
    cameraSelector,
    preview,
    videoCapture,
    SessionConfig.defaultSessionConfig(
        preferredFeatureGroup = listOf(
            GroupableFeature.HDR_HLG10,
            GroupableFeature.FPS_60,
            GroupableFeature.PREVIEW_STABILIZATION
        )
    )
)

With preferredFeatureGroup, CameraX tries your full list first, then drops features until it finds a combination the device supports. On a Pixel 10 Pro you get all three. On an older budget phone you might get just stabilization. Either way, no crash.

What Features Are Available

The current GroupableFeature set:

HDR_HLG10 — HDR video in HLG10 format
FPS_60 — 60 FPS recording
PREVIEW_STABILIZATION — Real-time stabilization during preview
IMAGE_ULTRA_HDR — Ultra HDR still image capture

More are expected as the API matures.

Building a UI That Doesn't Lie

The real win is building camera UIs that reflect what the device actually supports. Check each feature, then check combinations:

fun updateFeatureToggles(cameraInfo: CameraInfo) {
    hdrToggle.isEnabled = cameraInfo.isFeatureGroupSupported(
        setOf(GroupableFeature.HDR_HLG10)
    )
    fps60Toggle.isEnabled = cameraInfo.isFeatureGroupSupported(
        setOf(GroupableFeature.FPS_60)
    )
    stabilizationToggle.isEnabled = cameraInfo.isFeatureGroupSupported(
        setOf(GroupableFeature.PREVIEW_STABILIZATION)
    )
}

fun onFeatureToggled() {
    val requested = mutableSetOf<GroupableFeature>()
    if (hdrToggle.isChecked) requested.add(GroupableFeature.HDR_HLG10)
    if (fps60Toggle.isChecked) requested.add(GroupableFeature.FPS_60)
    if (stabilizationToggle.isChecked) requested.add(GroupableFeature.PREVIEW_STABILIZATION)

    if (cameraInfo.isFeatureGroupSupported(requested)) {
        recordButton.isEnabled = true
        warningText.visibility = View.GONE
    } else {
        recordButton.isEnabled = false
        warningText.text = "This combination isn't supported on your device"
        warningText.visibility = View.VISIBLE
    }
}

Users see exactly what their hardware can do. They can't select broken combos. Nobody gets to the crash.

`required` vs `preferred` — Pick the Right One

requiredFeatureGroup — all features must be supported, or bindToLifecycle() throws an IllegalArgumentException. Use it only when you genuinely can't ship without the specific combo (a pro video app where "HDR + 60 FPS" is the product).

preferredFeatureGroup — CameraX picks the best supported subset and never throws. Use this for almost everything.

One important gotcha with preferredFeatureGroup: it silently drops features it can't support. That's intentional, but make sure your UI reflects what actually ran — inspect the actual SessionConfig after binding, not the list you passed in. If the user toggled HDR + 60 FPS and they got HDR only, your record button shouldn't say otherwise.

What to Watch Out For in Production

Don't query before you have a CameraProvider. isFeatureGroupSupported() only works after cameraProvider.bindToLifecycle() has resolved. Call it in your ViewModel init block and you'll get a crash or stale data.

Configuration changes invalidate everything. Screen rotation, navigation pop-and-return — you have to re-bind the camera and re-check support. Don't cache support results across the UI lifecycle.

Camera ops are async — use coroutines. Wrap ListenableFuture<ProcessCameraProvider> in await(). Don't chain callbacks next to Feature Group logic or you'll have a race.

Front vs back camera. CameraInfo is camera-specific. Run the support check per cameraSelector — don't assume the back camera results apply to the front.

Dependencies

dependencies {
    val cameraxVersion = "1.6.1"
    implementation("androidx.camera:camera-camera2:$cameraxVersion")
    implementation("androidx.camera:camera-lifecycle:$cameraxVersion")
    implementation("androidx.camera:camera-video:$cameraxVersion")
}

Feature Groups graduated from experimental to stable in CameraX 1.5. The current stable is 1.6.1. Check the AndroidX CameraX release notes before pinning a version — the 1.6.x line has been adding groupable features steadily.

The Payoff

Before Feature Groups, a camera app that worked well across devices needed a combination of: manual device testing, a hard-coded compat list, or just disabling advanced features entirely and leaving flagship users with the same experience as budget users.

Now you query capabilities at runtime and build UI that adapts. Flagship gets flagship features. Budget gets what it supports. Nobody gets a crash report.

If you're touching camera code, this API earns its upgrade cost.

Originally published at suridevs.com

The Room Migration Mistake That Crashed Every User's App

SuriDevs — Wed, 06 May 2026 08:57:35 +0000

I crashed every existing user of my QR scanner app with one bad Room migration — added a label field, bumped the schema version, shipped, and watched the launch graph die. Below is everything I do now to avoid that, plus the entity/DAO/ViewModel patterns that turn Room from another framework chore into the fastest way to ship structured data on Android.

I shipped my first QR scanner app without scan history. Users complained. Fair enough - scanning the same WiFi QR code every time is annoying. So I added history using raw SQLite.

That was a mistake.

Cursor management, forgetting to close database connections, SQL typos that only crashed in production. I spent more time debugging database code than building actual features. When I rewrote it with Room, the scan history feature took an afternoon instead of a week.

Raw SQLite vs Room

Here's what fetching scan history looked like before Room:

fun getAllScans(): List<ScanRecord> {
    val scans = mutableListOf<ScanRecord>()
    val db = dbHelper.readableDatabase
    var cursor: Cursor? = null
    try {
        cursor = db.rawQuery(
            "SELECT * FROM scan_history ORDER BY timestamp DESC",
            null
        )
        while (cursor.moveToNext()) {
            scans.add(
                ScanRecord(
                    id = cursor.getLong(cursor.getColumnIndexOrThrow("id")),
                    content = cursor.getString(cursor.getColumnIndexOrThrow("content")),
                    format = cursor.getString(cursor.getColumnIndexOrThrow("format")),
                    timestamp = cursor.getLong(cursor.getColumnIndexOrThrow("timestamp")),
                    isFavorite = cursor.getInt(cursor.getColumnIndexOrThrow("is_favorite")) == 1
                )
            )
        }
    } finally {
        cursor?.close()
    }
    return scans
}

And here's the same thing with Room:

@Query("SELECT * FROM scan_history ORDER BY timestamp DESC")
fun getAllScans(): Flow<List<ScanRecord>>

One line. The SQL is checked at compile time. If I typo a column name, the build fails instead of crashing on a user's phone. And it returns a Flow, so my UI updates automatically when data changes.

Setup

Add these to your module's build.gradle.kts:

plugins {
    id("com.google.devtools.ksp")
}

dependencies {
    val roomVersion = "2.6.1"
    implementation("androidx.room:room-runtime:$roomVersion")
    implementation("androidx.room:room-ktx:$roomVersion")
    ksp("androidx.room:room-compiler:$roomVersion")
}

Use KSP, not KAPT. It's faster and Google recommends it now.

The Entity

An Entity is just a data class that maps to a database table. For scan history:

@Entity(tableName = "scan_history")
data class ScanRecord(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,
    val content: String,
    val format: String,
    val timestamp: Long,
    @ColumnInfo(name = "is_favorite")
    val isFavorite: Boolean = false,
    val label: String? = null
)

Few things I learned:

autoGenerate = true handles ID creation. Don't generate IDs yourself.
@ColumnInfo lets you use snake_case in the database while keeping camelCase in Kotlin. I prefer this because SQL conventions use underscores.
Nullable fields like label become nullable columns. Room handles this correctly.
Default values work. New scans get isFavorite = false automatically.

The DAO

This is where you define database operations. I use suspend functions for one-shot operations and Flow for data I want to observe.

@Dao
interface ScanDao {

    @Query("SELECT * FROM scan_history ORDER BY timestamp DESC")
    fun getAllScans(): Flow<List<ScanRecord>>

    @Query("SELECT * FROM scan_history WHERE is_favorite = 1 ORDER BY timestamp DESC")
    fun getFavorites(): Flow<List<ScanRecord>>

    @Query("SELECT * FROM scan_history WHERE content LIKE '%' || :query || '%'")
    fun searchScans(query: String): Flow<List<ScanRecord>>

    @Insert
    suspend fun insert(scan: ScanRecord)

    @Query("UPDATE scan_history SET is_favorite = NOT is_favorite WHERE id = :scanId")
    suspend fun toggleFavorite(scanId: Long)

    @Query("DELETE FROM scan_history WHERE id = :scanId")
    suspend fun delete(scanId: Long)

    @Query("DELETE FROM scan_history WHERE timestamp < :cutoffTime AND is_favorite = 0")
    suspend fun deleteOldScans(cutoffTime: Long)
}

The search query uses SQLite's LIKE with wildcards. Works fine for hundreds of records. If you're dealing with thousands, consider FTS (Full-Text Search), but I've never needed it for scan history.

That deleteOldScans query is useful - I run it on app launch to clear scans older than 30 days, but only if they're not favorited. Users don't lose their starred items.

Database Class

@Database(
    entities = [ScanRecord::class],
    version = 1
)
abstract class ScanDatabase : RoomDatabase() {
    abstract fun scanDao(): ScanDao
}

For dependency injection with Hilt:

@Module
@InstallIn(SingletonComponent::class)
object DatabaseModule {

    @Provides
    @Singleton
    fun provideDatabase(@ApplicationContext context: Context): ScanDatabase {
        return Room.databaseBuilder(
            context,
            ScanDatabase::class.java,
            "scan_database"
        ).build()
    }

    @Provides
    fun provideScanDao(database: ScanDatabase): ScanDao {
        return database.scanDao()
    }
}

The @Singleton annotation matters. You want one database instance for the entire app. Multiple instances cause locking issues and weird bugs.

ViewModel Integration

Here's how I connect the DAO to the UI:

@HiltViewModel
class ScanHistoryViewModel @Inject constructor(
    private val scanDao: ScanDao
) : ViewModel() {

    val scans: StateFlow<List<ScanRecord>> = scanDao.getAllScans()
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(5000),
            initialValue = emptyList()
        )

    fun onScanCompleted(content: String, format: String) {
        viewModelScope.launch {
            scanDao.insert(
                ScanRecord(
                    content = content,
                    format = format,
                    timestamp = System.currentTimeMillis()
                )
            )
        }
    }

    fun onToggleFavorite(scanId: Long) {
        viewModelScope.launch {
            scanDao.toggleFavorite(scanId)
        }
    }

    fun onDelete(scanId: Long) {
        viewModelScope.launch {
            scanDao.delete(scanId)
        }
    }
}

The WhileSubscribed(5000) keeps the Flow active for 5 seconds after the last subscriber disappears. This handles configuration changes - if the user rotates the screen, the Flow doesn't restart immediately.

In your Composable, just collect the state:

@Composable
fun ScanHistoryScreen(viewModel: ScanHistoryViewModel = hiltViewModel()) {
    val scans by viewModel.scans.collectAsStateWithLifecycle()

    LazyColumn {
        items(scans, key = { it.id }) { scan ->
            ScanItem(
                scan = scan,
                onFavoriteClick = { viewModel.onToggleFavorite(scan.id) },
                onDeleteClick = { viewModel.onDelete(scan.id) }
            )
        }
    }
}

When you insert, delete, or update a scan, the UI updates automatically. No manual refresh needed.

Migrations

This is where I messed up badly once.

I wanted to add a label field so users could add notes to scans. Simple change, right? I added the field to the Entity, bumped the version to 2, and shipped. The app crashed for every existing user.

Room doesn't know how to transform version 1 to version 2 automatically. You have to tell it:

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE scan_history ADD COLUMN label TEXT")
    }
}

// In your database builder
Room.databaseBuilder(context, ScanDatabase::class.java, "scan_database")
    .addMigrations(MIGRATION_1_2)
    .build()

The migration SQL runs once when a user with version 1 opens the app after updating. Their data stays intact.

You might see fallbackToDestructiveMigration() in tutorials. This deletes all user data when the schema changes. Fine for development, but never use it in production. Users will uninstall your app if their data disappears.

Mistakes I Made

Querying on the main thread. Room blocks this by default and crashes. If you see "Cannot access database on the main thread", you forgot to use a coroutine or background thread. All my DAO functions are either suspend or return Flow which handles threading automatically.

Forgetting @Transaction. If you're doing multiple database operations that should succeed or fail together, wrap them:

@Transaction
suspend fun replaceAllScans(scans: List<ScanRecord>) {
    deleteAll()
    insertAll(scans)
}

Without @Transaction, a crash between delete and insert leaves the database empty.

Not testing migrations. Room provides MigrationTestHelper for this. I didn't use it at first. Then I shipped a broken migration. Test your migrations.

Indexing. If you're querying by a specific column frequently (like searching by format), add an index:

@Entity(
    tableName = "scan_history",
    indices = [Index(value = ["format"])]
)

I didn't need this for scan history since the dataset is small, but it matters for larger tables.

When Room Isn't the Answer

Room is great for structured data with relationships. But sometimes it's overkill:

Simple key-value pairs: Use DataStore instead. User preferences, settings, feature flags.
Files or images: Store them in the filesystem, keep only the path in Room.
Huge datasets with complex queries: Consider SQLDelight or direct SQLite if you need more control.

For most apps though, Room handles everything you need.

Room turned database code from my least favorite part of Android development into something I don't think about much anymore. It just works. The compile-time SQL checking alone has saved me from countless production bugs.

Start simple - one Entity, one DAO, basic CRUD. Add complexity when you actually need it. You probably don't need FTS, triggers, or database views for your first feature. I certainly didn't for scan history.

Originally published at suridevs.com — for more Android and Kotlin articles, browse the full blog.

Advanced MVVM in Jetpack Compose: Search, Pagination & Cross-Module Triggers

SuriDevs — Mon, 04 May 2026 04:18:44 +0000

User types "android" into your search box. That's 7 API calls if you wired it the way I did the first time.

A few months later I shipped a pagination bug where every infinite-scroll fetch flashed a full-screen loader for half a second. And then there was the Settings screen that needed to refresh the Dashboard when the user changed theme — but Settings couldn't import Dashboard without a circular dependency.

These are the three problems I run into on every non-trivial Compose app. Below is the MVVM pattern I've landed on after making each of these mistakes in production.

(If you're new to MVVM with Compose, I covered the basics with a login screen separately. This article assumes you already know the StateFlow + ViewModel shape and goes one layer up.)

The Search Problem Everyone Gets Wrong

Here's how I used to implement search:

// Don't do this
searchTextField.addTextChangedListener { text ->
    viewModel.search(text.toString())  // API call on every keystroke!
}

User types "android" - that's 7 API calls. Type fast enough and you'll hit rate limits, burn through user's data, and probably show results for "andr" before "android" finishes loading.

The fix is debouncing - wait until the user stops typing, then search. In Compose with Flow, it looks like this:

private val searchQuery = MutableStateFlow("")

init {
    viewModelScope.launch {
        searchQuery
            .debounce(300)  // Wait 300ms after last keystroke
            .distinctUntilChanged()  // Skip if same as previous
            .flatMapLatest { query ->
                // Cancel previous search, start new one
                flow { emit(query) }
            }
            .collect { query ->
                searchItems(query)
            }
    }
}

fun onSearchQueryChanged(query: String) {
    searchQuery.value = query
}

Let me break down what each operator does because I was confused by these for weeks:

debounce(300) - Waits 300 milliseconds of "silence" before emitting. If user types another character before 300ms, the timer resets. Only when they stop typing for 300ms does the value get through.

distinctUntilChanged() - If the debounced value is the same as the last one (user typed "test", deleted the "t", then added it back), don't emit. Prevents duplicate API calls.

flatMapLatest - This one's important. If a new search comes in while the old one is running, cancel the old one. Otherwise you might show results for "andr" after results for "android" if the shorter query's API call finishes last.

Managing State When Things Get Complicated

A login screen has simple state - loading or not, maybe an error message. A searchable, paginated list? Way more complex.

Here's the state class I use:

data class ItemListState(
    val items: List<Item> = emptyList(),
    val isLoading: Boolean = false,
    val isLoadingMore: Boolean = false,
    val error: String? = null,
    val searchQuery: String = "",
    val hasMore: Boolean = true,
    val currentPage: Int = 0
)

The key insight: isLoading and isLoadingMore are separate. isLoading shows a full-screen spinner (first load or new search). isLoadingMore shows a spinner at the bottom of the list (pagination). I mixed these up once and users saw a full-screen loader every time they scrolled. Not great.

Here's the ViewModel that ties it all together:

@HiltViewModel
class ItemListViewModel @Inject constructor(
    private val getItemsUseCase: GetItemsUseCase,
    private val connectivityManager: ConnectivityManager
) : ViewModel() {

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

    private val searchQuery = MutableStateFlow("")

    init {
        viewModelScope.launch {
            searchQuery
                .debounce(300)
                .distinctUntilChanged()
                .flatMapLatest { query -> flow { emit(query) } }
                .collect { query ->
                    _state.value = _state.value.copy(searchQuery = query)
                    searchItems(query)
                }
        }

        loadItems()
    }

    fun onSearchQueryChanged(query: String) {
        searchQuery.value = query
    }

    private fun loadItems(isLoadingMore: Boolean = false) {
        if (!isNetworkAvailable()) {
            _state.value = _state.value.copy(
                isLoading = false,
                isLoadingMore = false,
                error = "No internet connection"
            )
            return
        }

        viewModelScope.launch {
            // Different loading states for initial load vs pagination
            if (isLoadingMore) {
                _state.value = _state.value.copy(isLoadingMore = true)
            } else {
                _state.value = _state.value.copy(isLoading = true, error = null)
            }

            try {
                val currentPage = if (isLoadingMore) _state.value.currentPage + 1 else 0
                val result = getItemsUseCase(
                    query = _state.value.searchQuery,
                    page = currentPage,
                    limit = 20
                )

                if (result.isSuccess) {
                    val newItems = result.items ?: emptyList()

                    _state.value = _state.value.copy(
                        // Append for pagination, replace for new search
                        items = if (isLoadingMore) {
                            _state.value.items + newItems
                        } else {
                            newItems
                        },
                        isLoading = false,
                        isLoadingMore = false,
                        hasMore = newItems.size >= 20,  // Got full page = probably more
                        currentPage = currentPage,
                        error = null
                    )
                } else {
                    _state.value = _state.value.copy(
                        isLoading = false,
                        isLoadingMore = false,
                        error = result.message ?: "Failed to load items"
                    )
                }
            } catch (e: Exception) {
                _state.value = _state.value.copy(
                    isLoading = false,
                    isLoadingMore = false,
                    error = e.message ?: "An error occurred"
                )
            }
        }
    }

    private fun searchItems(query: String) {
        // New search = reset to page 0
        _state.value = _state.value.copy(currentPage = 0, items = emptyList())
        loadItems(isLoadingMore = false)
    }

    fun onLoadMore() {
        // Don't load more if already loading or no more items
        if (!_state.value.isLoadingMore && _state.value.hasMore) {
            loadItems(isLoadingMore = true)
        }
    }

    fun onRetry() {
        loadItems(isLoadingMore = false)
    }

    private fun isNetworkAvailable(): Boolean {
        val network = connectivityManager.activeNetwork ?: return false
        val capabilities = connectivityManager.getNetworkCapabilities(network) ?: return false
        return capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
    }
}

The pagination logic is in that items = if (isLoadingMore) block. For pagination, append new items to the existing list. For a new search, replace the list entirely. I got this wrong in my first implementation and ended up with old search results mixed with new ones.

The UI Side

The UI needs to handle multiple states: loading, error, empty, and content. Here's how I structure it:

@Composable
fun ItemListScreen(
    viewModel: ItemListViewModel = hiltViewModel()
) {
    val state by viewModel.state.collectAsState()
    var searchText by remember { mutableStateOf("") }

    Column(modifier = Modifier.fillMaxSize()) {
        // Search bar
        OutlinedTextField(
            value = searchText,
            onValueChange = {
                searchText = it
                viewModel.onSearchQueryChanged(it)
            },
            modifier = Modifier
                .fillMaxWidth()
                .padding(16.dp),
            placeholder = { Text("Search items...") },
            leadingIcon = {
                Icon(Icons.Default.Search, contentDescription = "Search")
            },
            trailingIcon = {
                if (searchText.isNotEmpty()) {
                    IconButton(onClick = {
                        searchText = ""
                        viewModel.onSearchQueryChanged("")
                    }) {
                        Icon(Icons.Default.Clear, contentDescription = "Clear")
                    }
                }
            },
            singleLine = true
        )

        when {
            // Initial loading - show full screen spinner
            state.isLoading && state.items.isEmpty() -> {
                Box(
                    modifier = Modifier.fillMaxSize(),
                    contentAlignment = Alignment.Center
                ) {
                    CircularProgressIndicator()
                }
            }

            // Error with no items - show error with retry
            state.error != null && state.items.isEmpty() -> {
                ErrorView(
                    message = state.error!!,
                    onRetry = { viewModel.onRetry() }
                )
            }

            // No items, not loading - empty state
            state.items.isEmpty() && !state.isLoading -> {
                EmptyView(searchQuery = state.searchQuery)
            }

            // We have items - show the list
            else -> {
                LazyColumn(
                    modifier = Modifier.fillMaxSize(),
                    contentPadding = PaddingValues(16.dp),
                    verticalArrangement = Arrangement.spacedBy(12.dp)
                ) {
                    items(state.items) { item ->
                        ItemCard(item = item)
                    }

                    // Load more at bottom
                    if (state.hasMore) {
                        item {
                            LoadMoreButton(
                                isLoading = state.isLoadingMore,
                                onClick = { viewModel.onLoadMore() }
                            )
                        }
                    }
                }
            }
        }
    }
}

Notice searchText is local state (mutableStateOf) while the actual search happens through the ViewModel. The text field needs to update immediately as the user types - if you debounced the text field itself, it would feel laggy. The debounce happens on the ViewModel side, between typing and API calls.

Cross-Module Communication (The Hard Problem)

This one took me a while to figure out. Say you have a Settings module and a Dashboard module. User changes theme in Settings, Dashboard needs to reload with the new theme. But Settings can't import Dashboard (circular dependency) and you don't want to pass callbacks everywhere. If you're using nested navigation graphs per feature module (as I set up in the Navigation Component guide), this problem comes up even more. The newer Navigation 3 with type-safe navigation removes nested graphs entirely and uses entry decorators instead.

I used to reach for EventBus libraries, but they use reflection and are hard to debug. Now I use a SharedFlow-based trigger system.

First, define what kinds of triggers can happen:

// In a :core module that everyone depends on
sealed class TriggerType {
    object ThemeChanged : TriggerType()
    object UserLoggedOut : TriggerType()
    data class DataUpdated(val dataId: String) : TriggerType()
    object RefreshDashboard : TriggerType()
}

Then create a manager that handles emitting and listening:

@Singleton
class TriggerManager @Inject constructor() {

    private val _triggers = MutableSharedFlow<TriggerType>(
        replay = 0,  // One-time events, no replay
        extraBufferCapacity = 1,
        onBufferOverflow = BufferOverflow.DROP_OLDEST
    )

    val triggers: SharedFlow<TriggerType> = _triggers.shareIn(
        scope = CoroutineScope(SupervisorJob() + Dispatchers.Default),
        started = SharingStarted.WhileSubscribed(5000),
        replay = 0
    )

    suspend fun emitTrigger(trigger: TriggerType) {
        _triggers.emit(trigger)
    }
}

That WhileSubscribed(5000) is important - it keeps the flow active for 5 seconds after the last subscriber leaves. This handles screen rotation gracefully.

Settings emits:

@HiltViewModel
class SettingsViewModel @Inject constructor(
    private val triggerManager: TriggerManager
) : ViewModel() {

    fun onThemeChanged(isDarkMode: Boolean) {
        saveThemePreference(isDarkMode)

        viewModelScope.launch {
            triggerManager.emitTrigger(TriggerType.ThemeChanged)
        }
    }
}

Dashboard listens:

@HiltViewModel
class DashboardViewModel @Inject constructor(
    private val triggerManager: TriggerManager
) : ViewModel() {

    init {
        viewModelScope.launch {
            triggerManager.triggers.collect { trigger ->
                when (trigger) {
                    is TriggerType.ThemeChanged -> refreshDashboard()
                    is TriggerType.UserLoggedOut -> clearDashboard()
                    else -> { /* ignore */ }
                }
            }
        }
    }
}

No circular dependencies, type-safe (sealed class), and easy to test.

Flow Operators Cheat Sheet

I keep forgetting which operator does what. Here's my reference:

debounce(timeMillis) - Wait until the flow is "quiet" for the specified time. Use for search input.

distinctUntilChanged() - Skip if the new value equals the previous one. Prevents duplicate API calls.

flatMapLatest - When new value comes, cancel whatever the previous value started. Use when you only care about the latest result.

combine(flow1, flow2) { a, b -> } - Emit whenever either flow emits, combining latest values from both. Use when filtering by multiple criteria.

map { } - Transform each emitted value. Straightforward.

filter { } - Only emit values that pass the predicate. Use for things like "only search if query is 3+ characters."

Here's combine in action - filtering by both search query and category:

val searchQuery = MutableStateFlow("")
val selectedCategory = MutableStateFlow<Category?>(null)

combine(searchQuery, selectedCategory) { query, category ->
    Pair(query, category)
}.collect { (query, category) ->
    loadItems(query = query, category = category)
}

Error Handling That Doesn't Annoy Users

The worst is when an app shows "java.net.UnknownHostException: Unable to resolve host". Users don't know what that means. I translate errors to human-readable messages:

fun mapErrorToMessage(exception: Exception): String {
    return when (exception) {
        is UnknownHostException -> "No internet connection"
        is SocketTimeoutException -> "Request timed out. Try again."
        is HttpException -> when (exception.code()) {
            401 -> "Session expired. Please login again."
            404 -> "Item not found"
            in 500..599 -> "Server error. Please try again later."
            else -> "Something went wrong"
        }
        else -> "Something went wrong"
    }
}

And always check for network before making requests. Users in airplane mode deserve a clear message, not a 30-second wait followed by a cryptic error.

Retry with Exponential Backoff

Sometimes the server is just having a bad moment. Instead of failing immediately, retry a few times with increasing delays:

private suspend fun <T> retryWithBackoff(
    times: Int = 3,
    initialDelay: Long = 100,
    maxDelay: Long = 1000,
    factor: Double = 2.0,
    block: suspend () -> T
): T {
    var currentDelay = initialDelay
    repeat(times - 1) {
        try {
            return block()
        } catch (e: Exception) {
            delay(currentDelay)
            currentDelay = (currentDelay * factor).toLong().coerceAtMost(maxDelay)
        }
    }
    return block()  // Last attempt, let it throw if it fails
}

First retry after 100ms, second after 200ms, third after 400ms. If all fail, then show the error. This handles temporary network blips without bothering the user.

Wrapping Up

These patterns handle most of what I encounter in production apps:

Search: Debounce user input, cancel old searches with flatMapLatest, show immediate UI feedback

Pagination: Separate loading states, append vs replace logic, track whether there are more items

Cross-module communication: SharedFlow-based triggers, no direct dependencies between feature modules

Error handling: Human-readable messages, network checks before requests, retry with backoff

The code samples here are simplified but the patterns are what I use in production. The complexity is in getting the details right - which is why I wrote this post. I kept making the same mistakes until I had these patterns down.

Originally published at suridevs.com. The previous post in this series — MVVM Architecture with Authentication Flow — covers the basics if you want the prerequisite.

Flutter Dio Token Refresh: Fixing the Race Condition Most Tutorials Miss

SuriDevs — Fri, 01 May 2026 05:37:29 +0000

Quick experiment you can run in five minutes.

Open your Flutter app. Find a screen that fires multiple API calls on load — dashboard, profile, anything that does this:

@override
void initState() {
  super.initState();
  _loadProfile();
  _loadNotifications();
  _loadRecentActivity();
  _loadUnreadMessages();
}

Four API calls. Normal stuff.

Now expire your access token (manually, or wait it out) and reload. Open your network inspector and count how many times /auth/refresh gets called.

If you see 4, you have the race condition I shipped to production once. Twice, actually. Took three failed mitigations before I landed on the lock pattern below.

Here's what happens when 4 requests hit 401 at the same time:

All 4 requests fire simultaneously
All 4 get 401 Unauthorized (token expired)
All 4 try to refresh the token
Server processes 4 refresh requests
First one succeeds, returns new token
Next 3 use the OLD refresh token (already invalidated)
Those 3 fail, potentially logging out the user

I've seen this bug in production apps with millions of users. It's subtle — it doesn't happen every time. Just enough to generate confused user reports about "random logouts."

Let's fix it properly.

Step 1: Secure Token Storage

First, where are you storing tokens right now?

// If you're doing this, stop
SharedPreferences.setString('access_token', token);

SharedPreferences is not secure:

On Android: plain XML file in app directory
On iOS: plist file, unencrypted
On rooted/jailbroken devices: readable by other apps

For auth tokens, use platform secure storage:

// lib/core/services/token_manager.dart

import 'package:flutter_secure_storage/flutter_secure_storage.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

class TokenManager {
  static const _storage = FlutterSecureStorage(
    aOptions: AndroidOptions(
      encryptedSharedPreferences: true,
    ),
    iOptions: IOSOptions(
      accessibility: KeychainAccessibility.first_unlock,
    ),
  );

  static const String _accessTokenKey = 'access_token';
  static const String _refreshTokenKey = 'refresh_token';
  static const String _userIdKey = 'user_id';

  Future<void> saveTokens({
    required String accessToken,
    String? refreshToken,
  }) async {
    await _storage.write(key: _accessTokenKey, value: accessToken);
    if (refreshToken != null) {
      await _storage.write(key: _refreshTokenKey, value: refreshToken);
    }
  }

  Future<String?> getAccessToken() async {
    return await _storage.read(key: _accessTokenKey);
  }

  Future<String?> getRefreshToken() async {
    return await _storage.read(key: _refreshTokenKey);
  }

  Future<void> saveUserId(String userId) async {
    await _storage.write(key: _userIdKey, value: userId);
  }

  Future<String?> getUserId() async {
    return await _storage.read(key: _userIdKey);
  }

  Future<bool> isAuthenticated() async {
    final token = await getAccessToken();
    final userId = await getUserId();
    return token != null && token.isNotEmpty && userId != null;
  }

  Future<void> clearAll() async {
    await _storage.deleteAll();
  }
}

// Riverpod provider
final tokenManagerProvider = Provider<TokenManager>((ref) => TokenManager());

"What does encryptedSharedPreferences: true do?"

On Android 6.0+, it uses the Android Keystore to encrypt the data. Even on rooted devices, the tokens aren't readable as plain text.

"What's KeychainAccessibility.first_unlock?"

On iOS, it means the data is accessible after the user unlocks the device once after boot. It's a balance between security and usability. Other options:

Option	When Accessible	Use Case
`first_unlock`	After first unlock since boot	Most apps
`unlocked`	Only when device is unlocked	High security
`always`	Always, even when locked	Background refresh (less secure)

For auth tokens, first_unlock is the standard choice.

Step 2: The Token Refresh Lock

This is the solution to the race condition. One class, 40 lines:

// lib/core/network/token_refresh_lock.dart

import 'dart:async';

/// Ensures only one token refresh happens at a time.
///
/// When 4 requests get 401 simultaneously:
/// - First request acquires the lock, starts refreshing
/// - Requests 2, 3, 4 see lock is taken, wait for the result
/// - First request completes, all 4 get the new token
/// - All 4 retry their original request with the new token
class TokenRefreshLock {
  static Completer<String>? _refreshCompleter;
  static bool _isLoggedOut = false;

  /// Is a refresh currently in progress?
  static bool get isRefreshing => _refreshCompleter != null;

  /// Has the user been logged out due to refresh failure?
  static bool get isLoggedOut => _isLoggedOut;

  /// Try to acquire the lock.
  /// Returns a Completer if you got the lock (you should refresh).
  /// Returns null if someone else is already refreshing (you should wait).
  static Completer<String>? tryAcquire() {
    if (_refreshCompleter == null && !_isLoggedOut) {
      _refreshCompleter = Completer<String>();
      return _refreshCompleter;
    }
    return null;
  }

  /// Get the current completer to wait on.
  static Completer<String>? get currentCompleter => _refreshCompleter;

  /// Call when refresh succeeds. Waiting requests will receive the new token.
  static void complete(String newToken) {
    _refreshCompleter?.complete(newToken);
    _refreshCompleter = null;
  }

  /// Call when refresh fails. Waiting requests will receive the error.
  static void completeWithError(Object error) {
    _refreshCompleter?.completeError(error);
    _refreshCompleter = null;
    _isLoggedOut = true;  // Prevent further refresh attempts
  }

  /// Reset state (call after successful login).
  static void reset() {
    _refreshCompleter = null;
    _isLoggedOut = false;
  }
}

"Why a Completer instead of a simple boolean lock?"

Because the waiting requests need to receive the new token once the refresh completes. A Completer lets them do this:

// Request 2, 3, 4 do this:
final newToken = await TokenRefreshLock.currentCompleter!.future;
// Now they have the new token without making another refresh call

If we used a boolean, they'd have to poll: "Is it done yet? Is it done yet?" That's wasteful and introduces timing bugs.

"What's the _isLoggedOut flag for?"

Once a refresh fails (refresh token expired or revoked), there's no point trying again. Every subsequent 401 should just fail immediately. The user needs to log in again — no amount of retrying will fix it.

When that happens, the UI side needs to surface it cleanly — usually a snackbar saying "Your session expired" plus a redirect to the login screen, not a full-page error that confuses the user. Showing the right error state for auth failures is its own pattern on top of this network layer.

Step 3: DIO Provider with Interceptors

Now we wire everything together. This is the largest file, but every line has a purpose:

// lib/core/network/dio_provider.dart

import 'dart:io';
import 'package:dio/dio.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'api_config.dart';
import 'token_refresh_lock.dart';
import '../services/token_manager.dart';

final dioProvider = Provider<Dio>((ref) {
  final tokenManager = ref.read(tokenManagerProvider);

  final dio = Dio(
    BaseOptions(
      baseUrl: ApiConfig.fullBaseUrl,
      connectTimeout: ApiConfig.connectTimeout,
      receiveTimeout: ApiConfig.receiveTimeout,
      sendTimeout: ApiConfig.sendTimeout,
      headers: ApiConfig.defaultHeaders,
    ),
  );

  dio.interceptors.add(
    InterceptorsWrapper(
      // ────────────────────────────────────────────────────
      // REQUEST INTERCEPTOR
      // Runs before every request goes out
      // ────────────────────────────────────────────────────
      onRequest: (options, handler) async {
        final token = await tokenManager.getAccessToken();

        if (token != null && token.isNotEmpty) {
          options.headers['Authorization'] = 'Bearer $token';
        }

        // Optional: identify platform for backend analytics
        if (Platform.isAndroid) {
          options.headers['X-Platform'] = 'android';
        } else if (Platform.isIOS) {
          options.headers['X-Platform'] = 'ios';
        }

        return handler.next(options);
      },

      // ────────────────────────────────────────────────────
      // ERROR INTERCEPTOR
      // Runs when a request fails
      // ────────────────────────────────────────────────────
      onError: (error, handler) async {
        // Only handle 401 Unauthorized
        if (error.response?.statusCode != 401) {
          return handler.next(error);
        }

        final requestPath = error.requestOptions.path;

        // Never try to refresh when the auth endpoints themselves fail.
        // If /auth/refresh returns 401, we're done — user needs to log in again.
        // If /auth/login returns 401, that's just wrong credentials.
        if (requestPath.contains('/auth/login') ||
            requestPath.contains('/auth/refresh') ||
            requestPath.contains('/auth/register')) {
          return handler.next(error);
        }

        // Already logged out from a previous refresh failure?
        // Don't even try.
        if (TokenRefreshLock.isLoggedOut) {
          return handler.reject(error);
        }

        // ── Try to acquire the refresh lock ──
        final acquiredLock = TokenRefreshLock.tryAcquire();

        if (acquiredLock == null) {
          // Someone else is already refreshing. Wait for them.
          final completer = TokenRefreshLock.currentCompleter;

          if (completer != null) {
            try {
              // Wait for the other request to finish refreshing
              final newToken = await completer.future;

              // Retry our original request with the new token
              error.requestOptions.headers['Authorization'] = 'Bearer $newToken';
              final response = await dio.fetch(error.requestOptions);
              return handler.resolve(response);
            } catch (e) {
              // The refresh failed. Our request fails too.
              return handler.reject(error);
            }
          }
          return handler.reject(error);
        }

        // ── We got the lock. Time to refresh. ──
        try {
          final refreshToken = await tokenManager.getRefreshToken();

          if (refreshToken == null) {
            throw Exception('No refresh token available');
          }

          // Call the refresh endpoint
          final refreshResponse = await dio.post(
            '/auth/refresh',
            data: {'refresh_token': refreshToken},
          );

          if (refreshResponse.statusCode == 200) {
            // Extract token (adjust based on your API's response format)
            final newToken = refreshResponse.data['access_token'] ??
                refreshResponse.data['token'] ??
                refreshResponse.headers
                    .value('authorization')
                    ?.replaceFirst('Bearer ', '');

            if (newToken != null && newToken.isNotEmpty) {
              // Save the new tokens
              await tokenManager.saveTokens(
                accessToken: newToken,
                refreshToken: refreshResponse.data['refresh_token'],
              );

              // Release the lock — waiting requests get the new token
              TokenRefreshLock.complete(newToken);

              // Retry our original request
              error.requestOptions.headers['Authorization'] = 'Bearer $newToken';
              final response = await dio.fetch(error.requestOptions);
              return handler.resolve(response);
            }
          }

          throw Exception('Token refresh failed');
        } catch (e) {
          // Refresh failed. Release the lock with error.
          TokenRefreshLock.completeWithError(e);

          // Clear stored tokens — user is logged out
          await tokenManager.clearAll();

          // Reject with a clear error
          return handler.reject(
            DioException(
              requestOptions: error.requestOptions,
              error: 'Session expired. Please log in again.',
              type: DioExceptionType.badResponse,
            ),
          );
        }
      },
    ),
  );

  // Debug logging for development only
  if (!ApiConfig.isProduction) {
    dio.interceptors.add(
      LogInterceptor(
        requestBody: true,
        responseBody: true,
        logPrint: (obj) => print('🌐 $obj'),
      ),
    );
  }

  return dio;
});

Let's walk through the error interceptor flow:

Request fails with 401
        │
        ├── Is it an auth endpoint? ──Yes──► Pass through (don't refresh)
        │
        No
        │
        ├── Already logged out? ──Yes──► Reject immediately
        │
        No
        │
        ├── Try to acquire lock
        │
        ├── Lock acquired? ──No──► Wait for completer.future
        │                                    │
        Yes                                  └──► Retry with new token
        │
        ├── Call /auth/refresh
        │
        ├── Success? ──No──► completeWithError(), clearAll(), reject
        │
        Yes
        │
        ├── Save new tokens
        ├── complete(newToken)  ← Waiting requests wake up here
        └── Retry original request

Don't Forget: Reset on Login

When a user logs in successfully, reset the lock:

// In your AuthService or LoginViewModel
Future<bool> login(String email, String password) async {
  final response = await dio.post('/auth/login', data: {
    'email': email,
    'password': password,
  });

  if (response.statusCode == 200) {
    await tokenManager.saveTokens(
      accessToken: response.data['access_token'],
      refreshToken: response.data['refresh_token'],
    );

    // Important: clear the logged-out state
    TokenRefreshLock.reset();

    return true;
  }
  return false;
}

If you forget this, users who were logged out due to refresh failure won't be able to make authenticated requests even after logging in again.

Testing the Race Condition Fix

Here's how to verify it works:

void testTokenRefreshLock() async {
  // Simulate 4 requests getting 401 at the same time
  final results = await Future.wait([
    simulateExpiredTokenRequest('/profile'),
    simulateExpiredTokenRequest('/notifications'),
    simulateExpiredTokenRequest('/settings'),
    simulateExpiredTokenRequest('/messages'),
  ]);

  // Check network inspector:
  // - Should see only 1 call to /auth/refresh
  // - Should see all 4 original requests retried
}

In your network inspector, you should see:

GET /profile              → 401
GET /notifications        → 401
GET /settings             → 401
GET /messages             → 401
POST /auth/refresh        → 200  ← Only one!
GET /profile              → 200  (retried)
GET /notifications        → 200  (retried)
GET /settings             → 200  (retried)
GET /messages             → 200  (retried)

If you see 4 refresh calls, something's wrong with the lock implementation.

What We Have Now

lib/
└── core/
    ├── network/
    │   ├── api_config.dart
    │   ├── api_response.dart
    │   ├── api_error_handler.dart
    │   ├── token_refresh_lock.dart  ← NEW
    │   └── dio_provider.dart        ← NEW
    └── services/
        └── token_manager.dart       ← NEW

File	Responsibility
`token_manager.dart`	Secure token storage
`token_refresh_lock.dart`	Coordinate concurrent refresh attempts
`dio_provider.dart`	Configure DIO with auth interceptors

What's Next

In Part 3, we build the final layer: BaseApiService and repository pattern. This is where we get those clean API calls:

final response = await userRepository.getProfile();
if (response.success) {
  // done
}

We'll also put together the complete flow diagram and a checklist for production deployment.

Checklist Before Moving On

[ ] Tokens stored in FlutterSecureStorage, not SharedPreferences
[ ] TokenRefreshLock.reset() called after successful login
[ ] Auth endpoints (/login, /refresh, /register) excluded from refresh logic
[ ] Debug logging only in non-production builds
[ ] Tested with multiple simultaneous 401s — only 1 refresh call

See you in Part 3.

This is Part 2 of a 3-part series:

Part 1: Foundation — ApiConfig, ApiResponse, ErrorHandler
Part 2: Token Refresh (you're here) — TokenManager, TokenRefreshLock, DIO Interceptors
Part 3: Clean API Calls — BaseApiService, Repository pattern

Originally published at suridevs.com.

Flutter Riverpod: Loading, Error & Success States Guide

SuriDevs — Thu, 30 Apr 2026 04:45:13 +0000

Every Flutter dev I know has shipped at least one screen that gets stuck on a loading spinner with no error message in production. I've shipped two.

In this guide, you'll learn the production pattern I use with Riverpod for loading, error, and success states — forms, debounced search, pagination, snackbar errors — including the mistakes I made first and what I do differently now.

The Three States You Always Need

Every screen that fetches data has to handle three states.

Loading — request in flight, show a spinner or skeleton
Error — request failed, show a message with a retry path
Success — request returned data

Plus a fourth implicit one: empty — request succeeded but returned nothing.

Skip any of these and you ship "infinite spinner" bugs and "blank screen" bugs. I've shipped both. Both are embarrassing.

Common Mistakes Developers Make

Listing these up front so you can scan and check your own code. I've made every one in production.

1. Showing the loader forever. The API throws, the catch block is missing, and isLoading stays true until the user kills the app.

// ❌ BAD: no catch — loading never clears on error
Future<void> loadProducts() async {
  state = state.copyWith(isLoading: true);
  final products = await _repository.getProducts();
  state = state.copyWith(isLoading: false, products: products);
}

2. Ignoring the error state. Catch block exists but only logs to console. User sees stale data, frozen, no feedback.

3. Mixing loading and success. Showing the success UI while isLoading is still true creates flicker — and bugs like "button enabled but data not ready."

4. Not clearing previous errors. User retries after fixing their connection, but the old error message is still on screen because nothing reset it.

5. Showing raw error messages. DioException [DioExceptionType.connectionTimeout] is not a user-facing string. It's a stacktrace.

6. One errorMessage for everything. Page-load failures and "add to cart" failures need different UI. A single error field forces awkward compromises.

The rest of this article fixes these — by structuring your state, notifier, and UI consistently.

The State Class Pattern

Start with a state class. Always use copyWith. The trick most tutorials miss is making error fields intentionally nullable so passing null clears them.

class ProductState {
  final bool isLoading;
  final String? errorMessage;
  final List<Product> products;
  final bool isLoadingMore;

  const ProductState({
    this.isLoading = false,
    this.errorMessage,
    this.products = const [],
    this.isLoadingMore = false,
  });

  ProductState copyWith({
    bool? isLoading,
    String? errorMessage,
    List<Product>? products,
    bool? isLoadingMore,
  }) {
    return ProductState(
      isLoading: isLoading ?? this.isLoading,
      errorMessage: errorMessage,  // intentionally nullable — pass null to clear
      products: products ?? this.products,
      isLoadingMore: isLoadingMore ?? this.isLoadingMore,
    );
  }
}

Look closely at that one line: errorMessage: errorMessage. Not errorMessage ?? this.errorMessage.

Why this matters: the ?? version keeps old errors stuck. When you pass null to clear an error before a retry, null falls through to this.errorMessage and the old message stays. The bare errorMessage: errorMessage version actually lets null through.

Every retry deserves a clean slate. This pattern gives you one.

Why StateNotifier instead of AsyncValue?

Riverpod gives you two ways to model async state: StateNotifier<MyState> (with manual isLoading flags) and AsyncValue<T> (which has loading/error/data baked in). Both work. I reach for StateNotifier whenever a screen has more state than just "the data" — pagination flags, last-search-query, success messages, multiple coexisting errors. AsyncValue is cleaner when the screen really is just fetch one thing, render or error. The patterns in this article use StateNotifier because real production screens almost always need the extra fields.

The Notifier Pattern

Every async action follows the same shape:

Set isLoading = true, clear previous error
Try the API call
On success → loading off, data in
On failure → loading off, error in

class ProductNotifier extends StateNotifier<ProductState> {
  final ProductRepository _repository;

  ProductNotifier(this._repository) : super(const ProductState());

  Future<void> loadProducts() async {
    state = state.copyWith(isLoading: true, errorMessage: null);

    try {
      final products = await _repository.getProducts();
      state = state.copyWith(
        isLoading: false,
        products: products,
        errorMessage: null,
      );
    } catch (e) {
      state = state.copyWith(
        isLoading: false,
        errorMessage: 'Failed to load products. Please try again.',
      );
    }
  }
}

final productNotifierProvider =
    StateNotifierProvider<ProductNotifier, ProductState>((ref) {
  final repository = ref.read(productRepositoryProvider);
  return ProductNotifier(repository);
});

The order matters. Loading is set before the try block, and the error is cleared at the same time. On a retry after an error, the UI immediately shows the spinner instead of the old error hanging around.

In every app I've worked on, this is the single most copy-pasted method. Get the shape right once and the rest of the codebase follows.

One race condition to know about: if loadProducts fires twice in quick succession (user double-taps refresh), the second response overwrites the first regardless of which actually arrived first. For most screens this is fine — the second result is fresher. If you need stricter ordering, add a int _requestId counter and ignore responses whose ID is older than the latest.

Wiring the UI

The build method follows a strict order: loading → error → empty → success. Get this wrong and you ship bugs like "no data" appearing while still loading.

class ProductScreen extends ConsumerStatefulWidget {
  const ProductScreen({super.key});

  @override
  ConsumerState<ProductScreen> createState() => _ProductScreenState();
}

class _ProductScreenState extends ConsumerState<ProductScreen> {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addPostFrameCallback((_) {
      ref.read(productNotifierProvider.notifier).loadProducts();
    });
  }

  @override
  Widget build(BuildContext context) {
    final state = ref.watch(productNotifierProvider);
    return Scaffold(
      appBar: AppBar(title: const Text('Products')),
      body: _buildBody(state),
    );
  }

  Widget _buildBody(ProductState state) {
    if (state.isLoading) {
      return const Center(child: CircularProgressIndicator());
    }

    if (state.errorMessage != null && state.products.isEmpty) {
      return Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(state.errorMessage!),
            const SizedBox(height: 16),
            ElevatedButton(
              onPressed: () {
                ref.read(productNotifierProvider.notifier).loadProducts();
              },
              child: const Text('Retry'),
            ),
          ],
        ),
      );
    }

    if (state.products.isEmpty) {
      return const Center(child: Text('No products found'));
    }

    return ListView.builder(
      itemCount: state.products.length,
      itemBuilder: (context, index) {
        final product = state.products[index];
        return ListTile(
          title: Text(product.name),
          subtitle: Text('\$${product.price.toStringAsFixed(2)}'),
        );
      },
    );
  }
}

Two subtleties worth noting:

The error check is errorMessage != null && products.isEmpty. Only show the full-screen error when there's nothing to show. If stale data exists and a new request fails, keep the data and surface the error differently (covered later under blocking vs non-blocking errors).
addPostFrameCallback for the initial load avoids "modify state during build" warnings. This is the cleanest place to trigger first fetches.

Form Submissions Are a Different Shape

A "load this list" screen and a "submit this form" screen need different state shapes. Forms care about:

Loading (request in flight)
Success message (transient — show, then clear)
Error message (transient or persistent)
Whether the action completed (for navigation)

The state class below packs all of this in. Note the same intentional-null pattern from earlier — both errorMessage and successMessage need to be passable as null to clear them between actions.

class AddToCartState {
  final bool isLoading;
  final bool isSuccess;
  final String? errorMessage;
  final String? successMessage;

  const AddToCartState({
    this.isLoading = false,
    this.isSuccess = false,
    this.errorMessage,
    this.successMessage,
  });

  AddToCartState copyWith({
    bool? isLoading,
    bool? isSuccess,
    String? errorMessage,
    String? successMessage,
  }) {
    return AddToCartState(
      isLoading: isLoading ?? this.isLoading,
      isSuccess: isSuccess ?? this.isSuccess,
      errorMessage: errorMessage,
      successMessage: successMessage,
    );
  }
}

class AddToCartNotifier extends StateNotifier<AddToCartState> {
  final CartRepository _cartRepository;

  AddToCartNotifier(this._cartRepository) : super(const AddToCartState());

  Future<bool> addToCart({required String productId, required int quantity}) async {
    state = state.copyWith(
      isLoading: true,
      errorMessage: null,
      successMessage: null,
      isSuccess: false,
    );

    try {
      final response = await _cartRepository.addItem(
        productId: productId,
        quantity: quantity,
      );

      if (response.success) {
        state = state.copyWith(
          isLoading: false,
          isSuccess: true,
          successMessage: 'Item added to cart!',
        );
        return true;
      }

      state = state.copyWith(
        isLoading: false,
        errorMessage: response.message ?? 'Failed to add item',
      );
      return false;
    } catch (e) {
      state = state.copyWith(
        isLoading: false,
        errorMessage: 'Something went wrong. Please try again.',
      );
      return false;
    }
  }

  void clearMessages() {
    state = state.copyWith(errorMessage: null, successMessage: null);
  }
}

For the UI side, you don't want success/error messages baked into the screen body — they should be snackbars that flash and disappear. That's ref.listen's job. The screen below shows the button-with-inline-spinner pattern and uses ref.listen to fire snackbars off state changes without rebuilding the whole widget tree.

class CartScreen extends ConsumerWidget {
  const CartScreen({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final cartState = ref.watch(addToCartProvider);

    ref.listen<AddToCartState>(addToCartProvider, (previous, current) {
      if (current.successMessage != null) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(
            content: Text(current.successMessage!),
            backgroundColor: Colors.green,
          ),
        );
      }
      if (current.errorMessage != null) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(
            content: Text(current.errorMessage!),
            backgroundColor: Colors.red,
          ),
        );
      }
    });

    return Scaffold(
      body: Center(
        child: ElevatedButton(
          onPressed: cartState.isLoading
              ? null
              : () {
                  ref.read(addToCartProvider.notifier).addToCart(
                        productId: 'product_123',
                        quantity: 1,
                      );
                },
          child: cartState.isLoading
              ? const SizedBox(
                  width: 20,
                  height: 20,
                  child: CircularProgressIndicator(strokeWidth: 2),
                )
              : const Text('Add to Cart'),
        ),
      ),
    );
  }
}

Three rules I follow for any form action:

Disable the button while loading. onPressed: state.isLoading ? null : () => .... Stops users from spam-tapping.
Use ref.listen for snackbars and navigation, not ref.watch. Watch rebuilds; listen reacts. A snackbar on watch re-fires on every rebuild.
Replace button content with a small inline spinner, don't show a separate overlay. Layout doesn't jump.

This same shape applies to login forms, checkout submissions, profile updates — anything where the user taps and waits for confirmation.

Search With Debounce: When Loading IS the State

Search has a specific challenge. You can't fire an API call on every keystroke. You also can't wait for the user to submit. Debounce sits between.

class SearchState {
  final bool isLoading;
  final bool isLoadingMore;
  final String? errorMessage;
  final List<Product> results;
  final String currentQuery;
  final bool hasMoreResults;
  final int totalCount;

  const SearchState({
    this.isLoading = false,
    this.isLoadingMore = false,
    this.errorMessage,
    this.results = const [],
    this.currentQuery = '',
    this.hasMoreResults = false,
    this.totalCount = 0,
  });

  SearchState copyWith({
    bool? isLoading,
    bool? isLoadingMore,
    String? errorMessage,
    List<Product>? results,
    String? currentQuery,
    bool? hasMoreResults,
    int? totalCount,
  }) {
    return SearchState(
      isLoading: isLoading ?? this.isLoading,
      isLoadingMore: isLoadingMore ?? this.isLoadingMore,
      errorMessage: errorMessage,
      results: results ?? this.results,
      currentQuery: currentQuery ?? this.currentQuery,
      hasMoreResults: hasMoreResults ?? this.hasMoreResults,
      totalCount: totalCount ?? this.totalCount,
    );
  }
}

class SearchNotifier extends StateNotifier<SearchState> {
  final SearchRepository _repository;
  static const int _pageSize = 10;
  static const _debounceDuration = Duration(seconds: 1);
  Timer? _debounce;
  String? _previousQuery;

  SearchNotifier(this._repository) : super(const SearchState());

  void onQueryChanged(String query) {
    _debounce?.cancel();

    final trimmed = query.trim();
    if (trimmed.length <= 2) return;        // minimum 3 chars
    if (trimmed == _previousQuery) return;  // skip same query

    _debounce = Timer(_debounceDuration, () {
      _previousQuery = trimmed;
      _search(trimmed);
    });
  }

  Future<void> _search(String query) async {
    state = state.copyWith(
      isLoading: true,
      errorMessage: null,
      currentQuery: query,
    );

    try {
      final response = await _repository.search(
        query: query,
        limit: _pageSize,
        offset: 0,
      );

      if (response.success && response.data != null) {
        state = state.copyWith(
          isLoading: false,
          results: response.data!.items,
          totalCount: response.data!.totalCount,
          hasMoreResults: response.data!.items.length < response.data!.totalCount,
        );
      } else {
        state = state.copyWith(
          isLoading: false,
          errorMessage: response.message ?? 'Search failed',
        );
      }
    } catch (e) {
      state = state.copyWith(
        isLoading: false,
        errorMessage: 'Search failed. Please try again.',
      );
    }
  }

  @override
  void dispose() {
    _debounce?.cancel();
    super.dispose();
  }
}

What's worth pointing out:

Debounce is a state transition, not just an optimization. Between keystroke and request, the screen is in a "user is typing" state — neither loading nor showing fresh results. The 3-character minimum and _previousQuery guard prevent firing duplicate or trivial queries.
_debounce?.cancel() in dispose matters. Navigate away mid-typing and a stale request would otherwise fire after the screen is gone.
Search results often relate to other state. Cart quantity on a product card, for instance. If your search and cart both touch the same product data, keeping them in sync across providers is its own pattern worth understanding.

Pagination: Loading vs LoadingMore

Pagination needs a different loading flag. The first load shows a full-screen spinner. Loading the next page shows a small spinner at the bottom of the existing list. Same provider, different UI.

Future<void> loadMore() async {
  if (state.isLoadingMore) return;  // prevent duplicate calls

  state = state.copyWith(isLoadingMore: true);

  try {
    final moreProducts = await _repository.getProducts(offset: state.products.length);
    state = state.copyWith(
      isLoadingMore: false,
      products: [...state.products, ...moreProducts],
    );
  } catch (e) {
    state = state.copyWith(
      isLoadingMore: false,
      errorMessage: 'Failed to load more products.',
    );
  }
}

The list builder accommodates the loader as the last item:

return ListView.builder(
  itemCount: state.products.length + (state.isLoadingMore ? 1 : 0),
  itemBuilder: (context, index) {
    if (index == state.products.length) {
      return const Center(
        child: Padding(
          padding: EdgeInsets.all(16),
          child: CircularProgressIndicator(),
        ),
      );
    }
    final product = state.products[index];
    return ListTile(
      title: Text(product.name),
      subtitle: Text('\$${product.price.toStringAsFixed(2)}'),
    );
  },
);

Why two flags instead of one:

isLoading controls full-screen replacement (initial load, retry from empty)
isLoadingMore is additive — list stays visible, spinner at the bottom

Combine them and you're forced to choose between "hide the list while paginating" (jarring) and "show stale data with no indicator" (looks broken). Two flags is the easy way out.

Blocking vs Non-Blocking Errors

Not all errors deserve a full-screen takeover. The line:

Blocking — the user can't do anything useful with this screen until you fix it. Full-screen error with retry. Examples: list failed to load, no internet on first launch.
Non-blocking — the page is fine, but a specific action failed. Show a snackbar; don't disrupt the rest of the UI. Examples: "add to cart" failed, "save profile" failed.

Treating both the same is what makes apps feel clunky. A 500 on "add to cart" shouldn't blow away the product list the user was browsing.

class OrderState {
  final bool isLoading;
  final String? errorMessage;       // blocking — full screen
  final String? toastError;         // non-blocking — snackbar
  final List<Order> orders;
  final bool isPlacingOrder;
  final bool orderPlaced;

  const OrderState({
    this.isLoading = false,
    this.errorMessage,
    this.toastError,
    this.orders = const [],
    this.isPlacingOrder = false,
    this.orderPlaced = false,
  });

  // copyWith elided — same intentional-null pattern as before
}

How it gets wired up:

Loading the orders list fails → set errorMessage (full-screen retry).
Placing an order fails → set toastError (snackbar, list stays).
Order succeeds → set orderPlaced = true and navigate via ref.listen.

The UI reads both signals separately:

ref.listen<OrderState>(orderProvider, (previous, current) {
  if (current.toastError != null) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(current.toastError!), backgroundColor: Colors.red),
    );
  }
  if (current.orderPlaced) {
    Navigator.pushNamed(context, '/order-success');
  }
});

If your app talks to an authenticated API, a 401 mid-action is its own special case — not really blocking the screen, but you do need to refresh the token before retrying. That's where state handling meets the network layer, and I covered refreshing tokens cleanly with Dio interceptors separately.

Key Takeaways

After several apps, this is the checklist I run for every new screen.

State class

Use copyWith with intentionally-nullable error fields (null clears them).
Separate isLoading and isLoadingMore if the screen paginates.
Separate errorMessage and toastError if it has both blocking and non-blocking failures.

Notifier

Set loading = true and clear error in the same line, before the try.
Always wrap the API call in try/catch.
Set loading = false in both branches.
Translate raw exceptions to user-readable strings — never show DioException to the UI.

ref.watch() for state that drives rebuilds.
ref.listen() for side effects: snackbars, navigation, analytics.
ref.read() for one-shot actions: button taps, initState calls.
Build order: loading → error → empty → success.
Disable buttons while their action is in flight.
Replace button content with an inline spinner — no separate overlay.

Testing

Notifiers are pure Dart classes. Test them with a fake repository and expect calls against state after each action. No widget tree, no pumpAndSettle. State patterns this clean are one of the biggest practical wins of MVVM-style separation.

The whole point is to make screens predictable. Once your team agrees on the shape, every new screen looks the same. Onboarding gets faster, bugs become easier to track, and "why isn't this loader stopping?" turns from a debug session into a quick state check.

If you're already structuring your API calls with a clean repository layer underneath, this state pattern slots in naturally. I wrote about organizing Dio with a repository abstraction as a follow-up to that.

FAQ

How to handle loading state in Flutter Riverpod?

Add an isLoading boolean to your state class and toggle it inside your StateNotifier. Set isLoading = true and clear any previous error before the API call, then set isLoading = false in both the success and catch branches. In the UI, use ref.watch(provider) and check state.isLoading first — show a CircularProgressIndicator or shimmer skeleton when it's true. The build order should always be: loading → error → empty → success.

What is AsyncValue vs StateNotifier?

AsyncValue is Riverpod's built-in wrapper for "this is one piece of async data" — it has loading, error, and data states baked in and you pattern-match on them with .when(...). StateNotifier is a manual approach where you build your own state class with isLoading, errorMessage, and any other fields you need. Use AsyncValue for simple fetch-and-render screens. Use StateNotifier when the screen has more state than just the data — pagination flags, form success messages, last-search-query, multiple coexisting errors. Production screens almost always need StateNotifier.

How to show error in Flutter UI?

Two patterns depending on the error type. Blocking errors (page failed to load) — store in errorMessage, render a full-screen error widget with a retry button when state.errorMessage != null && state.products.isEmpty. Non-blocking errors (an action failed but the page is fine) — store in a separate toastError field and listen for changes with ref.listen, then call ScaffoldMessenger.of(context).showSnackBar(...) to flash a snackbar. Never show raw exception strings like DioException [DioExceptionType.connectionTimeout] to users — translate them to friendly messages inside your repository or notifier.

Originally published at suridevs.com.

Change App Language in Android (Jetpack Compose) — Runtime Locale Switch

SuriDevs — Thu, 09 Apr 2026 06:44:26 +0000

For years, runtime language switching on Android was painful. You'd update the Configuration, recreate the Activity, fight back-stack issues, and inevitably lose UI state somewhere along the way. Half the StackOverflow answers were outdated, the other half didn't survive a screen rotation.

Android 13 fixed this with per-app language preferences — a system-level API that handles locale persistence and recreation for you. And there's an AppCompat backport that gives you the same API on Android 5.0+.

I recently shipped this in a production app supporting 17 languages. Here's how it works, what the gotchas are, and a complete working example you can drop into a Compose project.

The Problem With the Old Approach

The classic way looked something like this:

// DON'T do this anymore
val config = resources.configuration
config.setLocale(Locale("es"))
resources.updateConfiguration(config, resources.displayMetrics)
recreate()

This had a long list of problems:

updateConfiguration is deprecated
You had to manually persist the choice and re-apply it on every Activity start
recreate() tore down your view tree, killing animations and transient UI state
Subclassing ContextWrapper to wrap attachBaseContext was a popular workaround — and a maintenance nightmare
System-level "language per app" in Settings → Apps → [Your App] didn't exist, so users had no way to override outside your settings screen

The New Approach (Android 13+)

In API 33, Google introduced two things:

LocaleManager — a system service for getting/setting per-app locales
System integration — users can change your app's language directly from Android Settings

For older devices, AppCompat 1.6+ ships a backport: AppCompatDelegate.setApplicationLocales(). It uses the system API on API 33+ and falls back to a SharedPreferences-backed persistence layer on older versions. Same call, both paths.

Both approaches handle Activity recreation automatically and preserve state correctly.

Setting Up Resource Folders

This part hasn't changed. Create one values-XX/ folder per language with a strings.xml:

app/src/main/res/
├── values/strings.xml          # default (English)
├── values-es/strings.xml       # Spanish
├── values-hi/strings.xml       # Hindi
└── values-ar/strings.xml       # Arabic (RTL)

A minimal strings.xml:

<!-- values/strings.xml -->
<resources>
    <string name="app_name">Recipe Notes</string>
    <string name="title_settings">Settings</string>
    <string name="label_language">Language</string>
    <string name="msg_welcome">Welcome to Recipe Notes</string>
</resources>

<!-- values-es/strings.xml -->
<resources>
    <string name="app_name">Notas de Recetas</string>
    <string name="title_settings">Ajustes</string>
    <string name="label_language">Idioma</string>
    <string name="msg_welcome">Bienvenido a Notas de Recetas</string>
</resources>

You also need to declare the supported locales in build.gradle.kts so the build system knows which languages to bundle:

android {
    defaultConfig {
        // ...
        resourceConfigurations += listOf("en", "es", "hi", "ar")
    }
}

This prevents Google Play from stripping unused locales when you upload an App Bundle, and it tells LocaleManager which locales your app actually supports.

The Locale Manager Wrapper

Here's the core helper. It works on Android 5.0+ by branching on API level:

import android.app.LocaleManager
import android.content.Context
import android.os.Build
import android.os.LocaleList
import androidx.appcompat.app.AppCompatDelegate
import androidx.core.os.LocaleListCompat

object LocaleHelper {

    /**
     * Set the app's language. Pass null or empty to follow system default.
     *
     * Examples:
     *   setAppLocale(context, "es")     -> Spanish
     *   setAppLocale(context, "hi")     -> Hindi
     *   setAppLocale(context, null)     -> Follow system
     */
    fun setAppLocale(context: Context, languageTag: String?) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
            // Android 13+ — use system LocaleManager
            val localeManager = context.getSystemService(LocaleManager::class.java)
            localeManager.applicationLocales = if (languageTag.isNullOrEmpty()) {
                LocaleList.getEmptyLocaleList()
            } else {
                LocaleList.forLanguageTags(languageTag)
            }
        } else {
            // Android 5.0–12 — use AppCompat backport
            val localeList = if (languageTag.isNullOrEmpty()) {
                LocaleListCompat.getEmptyLocaleList()
            } else {
                LocaleListCompat.forLanguageTags(languageTag)
            }
            AppCompatDelegate.setApplicationLocales(localeList)
        }
    }

    /**
     * Get the currently active language tag, or null if following system.
     */
    fun getCurrentLanguageTag(context: Context): String? {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
            val localeManager = context.getSystemService(LocaleManager::class.java)
            localeManager.applicationLocales[0]?.toLanguageTag()
        } else {
            AppCompatDelegate.getApplicationLocales()[0]?.toLanguageTag()
        }
    }
}

A few things worth noting:

Empty locale list = "follow system". This is the documented signal for both APIs. Don't pass null to forLanguageTags() or you'll get a crash.
The backport (AppCompatDelegate) persists the choice for you in its own internal storage. You don't need to wire up SharedPreferences yourself.
On Android 13+, the system LocaleManager persists too — and the user's choice survives even if your app data is partially cleared.

LocaleManager vs AppCompatDelegate

Here's a quick comparison so you know what each path does:

Feature	LocaleManager (API 33+)	AppCompatDelegate (backport)
Min API	33	14 (works back to 5.0 via AppCompat)
Persistence	System-managed	App-internal SharedPreferences
Visible in system Settings	Yes (per-app language)	No
Survives app data clear	Partially (system stores it)	No
Triggers Activity recreate	Yes	Yes
Locale fallback	System handles	AppCompat handles

The good news: you write the call once. The wrapper above branches automatically.

A ViewModel for Language State

Wrapping the locale helper in a ViewModel keeps your Compose UI clean and gives you a single source of truth:

import android.app.Application
import androidx.lifecycle.AndroidViewModel
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow

data class Language(val tag: String?, val label: String)

class LanguageViewModel(application: Application) : AndroidViewModel(application) {

    val supportedLanguages = listOf(
        Language(null, "System default"),
        Language("en", "English"),
        Language("es", "Español"),
        Language("hi", "हिन्दी"),
        Language("ar", "العربية")
    )

    private val _selectedTag = MutableStateFlow(
        LocaleHelper.getCurrentLanguageTag(application)
    )
    val selectedTag: StateFlow<String?> = _selectedTag.asStateFlow()

    fun changeLanguage(tag: String?) {
        LocaleHelper.setAppLocale(getApplication(), tag)
        _selectedTag.value = tag
    }
}

A Compose Settings Screen

Now the UI. This is a minimal language picker using Material 3's ExposedDropdownMenuBox:

import androidx.compose.foundation.layout.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.runtime.collectAsState
import androidx.compose.ui.Modifier
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.unit.dp
import androidx.lifecycle.viewmodel.compose.viewModel

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun LanguageSettingsScreen(
    viewModel: LanguageViewModel = viewModel()
) {
    val selectedTag by viewModel.selectedTag.collectAsState()
    val languages = viewModel.supportedLanguages
    val currentLanguage = languages.firstOrNull { it.tag == selectedTag }
        ?: languages.first()

    var expanded by remember { mutableStateOf(false) }

    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(16.dp)
    ) {
        Text(
            text = stringResource(R.string.title_settings),
            style = MaterialTheme.typography.headlineSmall
        )

        Spacer(Modifier.height(24.dp))

        ExposedDropdownMenuBox(
            expanded = expanded,
            onExpandedChange = { expanded = it }
        ) {
            OutlinedTextField(
                value = currentLanguage.label,
                onValueChange = {},
                readOnly = true,
                label = { Text(stringResource(R.string.label_language)) },
                trailingIcon = {
                    ExposedDropdownMenuDefaults.TrailingIcon(expanded = expanded)
                },
                modifier = Modifier
                    .menuAnchor()
                    .fillMaxWidth()
            )

            ExposedDropdownMenu(
                expanded = expanded,
                onDismissRequest = { expanded = false }
            ) {
                languages.forEach { language ->
                    DropdownMenuItem(
                        text = { Text(language.label) },
                        onClick = {
                            viewModel.changeLanguage(language.tag)
                            expanded = false
                        }
                    )
                }
            }
        }

        Spacer(Modifier.height(24.dp))

        Text(
            text = stringResource(R.string.msg_welcome),
            style = MaterialTheme.typography.bodyLarge
        )
    }
}

When the user picks a language, changeLanguage() calls into the helper, which calls LocaleManager or AppCompatDelegate. The system handles the Activity recreation, your composables re-resolve stringResource() against the new locale, and the welcome message updates instantly.

You don't need recreate(). You don't need to wrap attachBaseContext. You don't need Configuration.setLocale. It just works.

Handling System Default

The "System default" entry maps to a null tag. When the user picks it, we pass null to setAppLocale, which sets an empty locale list. The system then falls back to whatever the device language is.

If the user later changes their device language in system settings, your app picks it up automatically — no code on your side. That's the beauty of the empty-list signal.

RTL Gotcha

Arabic, Hebrew, Urdu, and Farsi are right-to-left languages. Compose handles most of the layout mirroring for you, but you need two things:

1. Declare RTL support in AndroidManifest.xml:

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

2. Use start and end instead of left and right in your modifiers and alignments:

// Good — mirrors automatically in RTL
Row(horizontalArrangement = Arrangement.Start) { ... }
Modifier.padding(start = 16.dp)

// Bad — stays on the physical left even in Arabic
Modifier.padding(left = 16.dp)

If you stick to start/end, your layouts will mirror correctly when the user switches to Arabic.

Common Mistakes

1. Forgetting to add resourceConfigurations in build.gradle

Without it, Play Store may strip locales from your App Bundle download. Users get the default values/ strings even after switching language.

2. Hardcoding strings in Composables

// Bad
Text("Welcome")

// Good
Text(stringResource(R.string.msg_welcome))

Hardcoded strings won't react to locale changes because they're not resources.

3. Caching context references across recreates

When setApplicationLocales triggers an Activity recreate, your old Activity and its Context get destroyed. If you stored a reference somewhere (a singleton, a static field), you're now holding a stale Context. Always grab the current context inside your composable or ViewModel.

4. Calling recreate() yourself

You don't need to. The locale APIs trigger recreation for you. Calling recreate() on top causes a double-recreate and looks janky.

5. Mixing Locale("es") with forLanguageTags("es")

Stick to language tags (forLanguageTags). The Locale constructor is older and has some weird edge cases around region codes. Tags like "zh-CN" and "pt-BR" work cleanly.

6. Using only AppCompatDelegate on Android 13+

This one bit me. If you only call AppCompatDelegate.setApplicationLocales() and skip the LocaleManager path, the change works on most devices — but on some Android 13+ OEM builds it silently fails to persist after process death. The user picks Spanish, kills the app, reopens it, and they're back to English.

The fix is the dual-path wrapper shown earlier: call LocaleManager directly on API 33+, fall back to AppCompatDelegate only on older versions. Don't rely on AppCompat alone once you're targeting Android 13+.

7. Crashing when parsing locale tags from unknown sources

If you ever parse a language tag from an external source — a config file, a deep link parameter, an app split name, anything you didn't generate yourself — wrap it in a try/catch:

val locale = try {
    Locale.forLanguageTag(tag).takeIf { it.language.isNotEmpty() }
} catch (e: IllformedLocaleException) {
    null
}

Strings that look like locale tags but aren't (config.etc2, group_high_performance, random user input) will throw IllformedLocaleException from the strict parser. I've seen this crash a release build because a code path assumed every config.* string was a valid locale. Validate at the boundary.

Testing Tips

When testing locally:

Toggle through every language at least once after a fresh install — it catches missing translations early
Test on both an Android 12 device and an Android 13+ device — the code paths are different
Open system Settings → Apps → Your App on Android 13+ — you should see a "Language" entry. If you don't, check that LocaleConfig is set up (more on that below)
Rotate the screen after changing language — make sure state survives

Bonus: LocaleConfig for Android 13+

For Android 13+ to show your language picker in system Settings, declare a LocaleConfig XML file:

res/xml/locales_config.xml:

<?xml version="1.0" encoding="utf-8"?>
<locale-config xmlns:android="http://schemas.android.com/apk/res/android">
    <locale android:name="en"/>
    <locale android:name="es"/>
    <locale android:name="hi"/>
    <locale android:name="ar"/>
</locale-config>

Reference it in AndroidManifest.xml:

<application
    android:localeConfig="@xml/locales_config"
    ...>

Now your app shows up in Settings → System → Languages → App languages, and users can change your app's language without ever opening it.

Wrapping Up

The Android 13 per-app language APIs solve a problem that haunted Android developers for a decade. The migration is small — replace your old ContextWrapper hack with LocaleHelper.setAppLocale() and let the system handle the rest. You get state preservation, system Settings integration, and a cleaner codebase as a bonus.

If you're building the rest of your settings screen in Compose, you might also be looking at theme switching — light/dark/system. The same ViewModel + StateFlow pattern works there too, just swap LocaleHelper for an AppCompatDelegate.setDefaultNightMode() call.

And if you're starting a fresh project, set up your values/, values-es/, etc. folders from day one — even with just one language. Retrofitting localization into a codebase full of hardcoded strings is one of the most tedious refactors I've ever done. Future you will be grateful.

Originally published on SuriDevs. Follow me for more Android + Jetpack Compose tutorials.

R8 optimizedResourceShrinking: Reduce Android APK Size by 50%

SuriDevs — Mon, 30 Mar 2026 10:15:28 +0000

Resource shrinking has been around forever, but it's always been... okay. You enable it, you get some size reduction, but there's always unused stuff that slips through.

Android Gradle Plugin 8.12 changes this. Google integrated resource shrinking directly into R8's optimization pipeline, and the results are noticeably better.

What is Android Resource Shrinking?

Android apps have two types of bloat: code and resources. They need different tools to clean up.

Code shrinking (R8/ProGuard) removes unused Kotlin/Java classes, methods, and fields from your compiled code. If you wrote a utility class but never call it, R8 strips it out.

Resource shrinking removes unused drawables, layouts, strings, and other XML/binary resources from the final APK. That splash screen you deleted from code but forgot to remove from res/drawable? Resource shrinking catches it.

The key insight: these two are connected. Dead code might reference resources, and unused resources might only exist because dead code references them. When you optimize them separately, both miss things. That's exactly what optimizedResourceShrinking fixes — it runs both in the same pipeline.

How R8 optimizedResourceShrinking Works

The traditional flow looked like this:

AAPT2 compiles resources and generates keep rules
R8 shrinks and optimizes code
Resource shrinking runs as a separate post-processing step

The problem: AAPT2's keep rules were unconditional. It couldn't know which resources R8 would determine are unreachable. So it kept everything that might be used.

With optimizedResourceShrinking, R8 handles both in a single pass:

R8 analyzes code reachability (which classes/methods are actually called)
Simultaneously, it builds a resource reference graph (which resources are referenced by reachable code)
Resources only referenced by dead code get removed along with that dead code

This means R8 can see the full picture. If a feature flag disables a module at compile time, both the module's code AND its resources get stripped.

Why the Old Approach Leaked Resources

Traditional resource shrinking worked as a separate step from code optimization. AAPT2 would generate keep rules, R8 would do its thing, and then resource shrinking would run. The problem: those AAPT2 keep rules were unconditional.

This meant:

Code referencing unused resources stayed in the APK
Resources only used by dead code stayed too
Neither optimizer could see the full picture

The new approach runs both in the same R8 pipeline. Resources and code get analyzed together, so if code is dead, its resources go away too. And vice versa.

Enabling It

Add this to gradle.properties:

android.r8.optimizedResourceShrinking=true

You also need both minification and resource shrinking enabled in your release build:

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

That's it. Build your release APK and compare sizes.

What Kind of Reduction to Expect

Google claims 50%+ for apps with shared resources. In practice, it depends heavily on your app structure.

If you have a lot of library resources you don't use, or feature modules with resources only used in specific configurations, you'll see bigger gains. If your app is already lean and every resource is directly referenced, the improvement will be smaller.

Use APK Analyzer (Build → Analyze APK in Android Studio) to see where your size is actually coming from. Compare before and after - the res/ folder size should drop noticeably.

Watch Out For Dynamic Resource Loading

The biggest gotcha: resources loaded by string name at runtime.

// This will break - the optimizer can't see this reference
val resId = resources.getIdentifier("icon_$category", "drawable", packageName)

The optimizer doesn't know you're using those resources, so it removes them. Your app crashes with Resources$NotFoundException.

Fix it either by using direct references:

val resId = when(category) {
    "food" -> R.drawable.icon_food
    "travel" -> R.drawable.icon_travel
    else -> R.drawable.icon_default
}

Or by adding a keep file at res/raw/keep.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@drawable/icon_*" />

ProGuard Rules for Resources

If you need to keep specific resources that are referenced dynamically:

# Keep resources referenced by name at runtime
-keep class **.R$drawable {
    public static final int splash_logo;
    public static final int app_icon_*;
}

Testing Your Build

After enabling optimized shrinking:

Build a release APK
Install and test the app thoroughly
Pay special attention to features that load resources dynamically
Test on different device configurations (screen densities, languages)

If something breaks, check your dynamic resource loading first. Nine times out of ten, that's the issue.

Common Problems With Resource Shrinking

After enabling this on multiple projects, here are the issues I've hit:

1. Reflection-based resource access

Libraries that load resources by name at runtime will break. This is the most common issue. If you use a library that dynamically constructs resource names (like some icon packs or theme engines), you need to add keep rules.

2. Library resources you don't use

Third-party libraries bundle their own resources — icons, layouts, strings. With optimized shrinking, R8 is more aggressive about removing these. Occasionally a library accesses its own resources through reflection, and shrinking breaks it. The fix is usually a ProGuard keep rule from the library's documentation.

3. WebView HTML referencing Android resources

If your WebView loads local HTML that references file:///android_res/drawable/image.png, the shrinking won't see that reference. Those resources get removed and your WebView shows broken images. Move these assets to assets/ instead of res/.

4. Multi-module resource conflicts

In multi-module projects, resources with the same name in different modules can cause unexpected behavior when shrinking. Use resource prefixes (resourcePrefix "module_" in build.gradle) to avoid collisions.

Before and After: Real Numbers

Here's what I measured on our APK Manager app (https://www.suridevs.com/blog/posts/apk-manager-backup-restore-guide/) after enabling optimized shrinking:

Metric	Before	After
Total APK size	25.1 MB	13.2 MB
`res/` folder	14.8 MB	5.1 MB
`classes.dex`	6.2 MB	4.9 MB
Unused drawables removed	—	847
Unused strings removed	—	2,130

The biggest savings came from library resources we never used. Our app included Material Components, and the default theme bundles hundreds of drawables for widgets we never touch.

When It Becomes Default

Optimized resource shrinking is opt-in now, but it'll become the default in AGP 9.0.0. If you enable it now, you get ahead of any issues before you're forced to deal with them.

Is It Worth It?

For most apps, yes. The size reduction is real, and smaller APKs mean faster downloads and less storage pressure on user devices. The main cost is testing and potentially updating any dynamic resource loading patterns.

If you're distributing APKs directly (not through Play's AAB splitting), the savings are even more valuable since you're not getting per-device optimization anyway. For more on how APK packaging and split APKs work under the hood, see the Android PackageManager and ZIP64 APK guide at https://www.suridevs.com/blog/posts/apk-manager-backup-restore-guide/.

If you're building a Compose app and want to keep the overall architecture clean while optimizing, check out the MVVM Architecture guide at https://www.suridevs.com/blog/posts/mvvm-jetpack-compose-authentication-guide/.

Full technical details in Google's announcement.

Originally published at SuriDevs

Jetpack Compose Layouts: When to Use Row, Column, Box & ConstraintLayout

SuriDevs — Fri, 20 Mar 2026 05:52:14 +0000

Every time I start a new screen in Compose, I ask myself the same question: Row, Column, Box, or ConstraintLayout?

After building 40+ production screens across multiple apps, I've developed a pretty clear mental model for which layout to use when. The short version: Row, Column, and Box handle about 90% of what you'll ever need. ConstraintLayout fills the remaining 10% — but that 10% would be miserable without it.

Here's what I've learned.

Row, Column, Box — When to Use Each

These three are your workhorses. If you're coming from XML, think of them as replacements for LinearLayout(horizontal), LinearLayout(vertical), and FrameLayout.

Column — items stacked vertically. Use it for forms, lists of settings, card content, basically anything that reads top to bottom.

Column(modifier = Modifier.padding(16.dp)) {
    Text("Order #1234", style = MaterialTheme.typography.titleMedium)
    Spacer(modifier = Modifier.height(4.dp))
    Text("Placed on March 15, 2026", style = MaterialTheme.typography.bodySmall)
    Spacer(modifier = Modifier.height(12.dp))
    Text("3 items · $47.99", style = MaterialTheme.typography.bodyMedium)
}

Row — items laid out horizontally. Profile headers, action button groups, icon + text combos.

Row(
    modifier = Modifier.fillMaxWidth(),
    verticalAlignment = Alignment.CenterVertically
) {
    AsyncImage(
        model = user.avatarUrl,
        contentDescription = null,
        modifier = Modifier
            .size(48.dp)
            .clip(CircleShape)
    )
    Spacer(modifier = Modifier.width(12.dp))
    Column {
        Text(user.displayName, fontWeight = FontWeight.SemiBold)
        Text(user.role, style = MaterialTheme.typography.bodySmall)
    }
}

Box — items stacked on top of each other (z-axis). Overlays, badges, loading states on top of content.

Box(modifier = Modifier.fillMaxSize()) {
    LazyColumn { /* ... */ }

    FloatingActionButton(
        onClick = { /* ... */ },
        modifier = Modifier
            .align(Alignment.BottomEnd)
            .padding(16.dp)
    ) {
        Icon(Icons.Default.Add, contentDescription = "Add")
    }
}

My rule: if items go down the screen, Column. Side by side, Row. On top of each other, Box. You'd be surprised how far this gets you.

ConstraintLayout in Compose — When You Actually Need It

Here's the thing most tutorials don't tell you: you probably don't need ConstraintLayout in Compose.

In XML, ConstraintLayout solved a real problem — deeply nested LinearLayout and RelativeLayout trees that killed performance. But Compose's layout system is fundamentally different. Nesting Row inside Column inside Box doesn't create the same performance overhead because Compose uses a single-pass measurement system.

So when do I actually reach for ConstraintLayout in Compose?

1. Complex cross-references between siblings. When View A's position depends on View B's size, and View C needs to align with both.

2. Overlapping views with constraint-based positioning. Box handles simple overlaps, but when you need "this view's bottom aligns with that view's center, offset by 8dp" — that's constraint territory.

3. Barrier-based layouts. When you need a dynamic boundary that adjusts based on multiple views. There's no Row/Column equivalent for barriers.

4. Percentage-based positioning. Guidelines at 30% from the left, for example.

For everything else — and I mean the vast majority of screens — Row, Column, and Box are simpler, more readable, and perform the same.

Arrangement & Alignment

This confused me for weeks when I started with Compose. Here's the simple version:

Arrangement = how items are distributed along the main axis (horizontal for Row, vertical for Column).

Alignment = how items are positioned on the cross axis.

Row(
    modifier = Modifier.fillMaxWidth(),
    horizontalArrangement = Arrangement.SpaceEvenly,
    verticalAlignment = Alignment.CenterVertically
) {
    Icon(Icons.Default.Home, contentDescription = "Home")
    Icon(Icons.Default.Search, contentDescription = "Search")
    Icon(Icons.Default.Person, contentDescription = "Profile")
}

Arrangement.spacedBy() is the one I use 80% of the time. Fixed spacing between items. Clean and predictable.

Weight & Sizing

Weight in Compose works like layout_weight in XML's LinearLayout, but the API is cleaner:

Row(modifier = Modifier.fillMaxWidth()) {
    Text(
        text = product.name,
        modifier = Modifier.weight(0.7f),
        maxLines = 1,
        overflow = TextOverflow.Ellipsis
    )
    Text(
        text = product.price,
        modifier = Modifier.weight(0.3f),
        textAlign = TextAlign.End
    )
}

The gotcha I hit early on: weight is only available inside Row and Column scope. You can't use it inside Box.

Another pattern I use constantly — one item takes remaining space:

Row(
    modifier = Modifier.fillMaxWidth(),
    verticalAlignment = Alignment.CenterVertically
) {
    Text(
        text = "Settings",
        modifier = Modifier.weight(1f)
    )
    Switch(
        checked = isEnabled,
        onCheckedChange = { isEnabled = it }
    )
}

The weight(1f) on the text pushes the switch to the far right. No spacers needed.

Advanced Layouts with ConstraintLayout in Compose

When you do need ConstraintLayout, here's how the XML concepts translate.

Setup

dependencies {
    implementation("androidx.constraintlayout:constraintlayout-compose:1.1.1")
}

Chains

Link multiple composables for distribution:

ConstraintLayout(modifier = Modifier.fillMaxWidth()) {
    val (btn1, btn2, btn3) = createRefs()
    createHorizontalChain(btn1, btn2, btn3, chainStyle = ChainStyle.SpreadInside)

    Button(
        onClick = { },
        modifier = Modifier.constrainAs(btn1) {
            top.linkTo(parent.top)
        }
    ) { Text("Save") }

    Button(
        onClick = { },
        modifier = Modifier.constrainAs(btn2) {
            top.linkTo(parent.top)
        }
    ) { Text("Edit") }

    Button(
        onClick = { },
        modifier = Modifier.constrainAs(btn3) {
            top.linkTo(parent.top)
        }
    ) { Text("Delete") }
}

Guidelines

Invisible anchor lines at a percentage position:

ConstraintLayout(modifier = Modifier.fillMaxSize()) {
    val guideline = createGuidelineFromStart(fraction = 0.35f)
    val (image, content) = createRefs()

    Image(
        painter = painterResource(R.drawable.product),
        contentDescription = null,
        modifier = Modifier.constrainAs(image) {
            start.linkTo(parent.start)
            end.linkTo(guideline)
            width = Dimension.fillToConstraints
        }
    )

    Column(
        modifier = Modifier.constrainAs(content) {
            start.linkTo(guideline, margin = 12.dp)
            end.linkTo(parent.end)
            top.linkTo(parent.top)
            width = Dimension.fillToConstraints
        }
    ) {
        Text("Product Title", fontWeight = FontWeight.Bold)
        Text("Description goes here")
    }
}

Barriers

This is where ConstraintLayout genuinely shines — no Row/Column equivalent exists:

ConstraintLayout(modifier = Modifier.fillMaxWidth()) {
    val (label1, label2, input1, input2) = createRefs()
    val barrier = createEndBarrier(label1, label2)

    Text(
        text = "Name",
        modifier = Modifier.constrainAs(label1) {
            start.linkTo(parent.start)
            top.linkTo(parent.top)
        }
    )

    Text(
        text = "Email Address",
        modifier = Modifier.constrainAs(label2) {
            start.linkTo(parent.start)
            top.linkTo(label1.bottom, margin = 16.dp)
        }
    )

    OutlinedTextField(
        value = name,
        onValueChange = { name = it },
        modifier = Modifier.constrainAs(input1) {
            start.linkTo(barrier, margin = 12.dp)
            end.linkTo(parent.end)
            top.linkTo(label1.top)
            width = Dimension.fillToConstraints
        }
    )

    OutlinedTextField(
        value = email,
        onValueChange = { email = it },
        modifier = Modifier.constrainAs(input2) {
            start.linkTo(barrier, margin = 12.dp)
            end.linkTo(parent.end)
            top.linkTo(label2.top)
            width = Dimension.fillToConstraints
        }
    )
}

The barrier sits after whichever label is wider. Both input fields align perfectly regardless of label text length.

Real Example: Product Card

Here's a product card I built for an e-commerce app:

@Composable
fun ProductCard(product: Product, onAddToCart: () -> Unit) {
    ConstraintLayout(
        modifier = Modifier
            .fillMaxWidth()
            .padding(12.dp)
    ) {
        val (image, title, price, originalPrice, badge, cartBtn) = createRefs()

        AsyncImage(
            model = product.imageUrl,
            contentDescription = product.name,
            modifier = Modifier
                .constrainAs(image) {
                    top.linkTo(parent.top)
                    start.linkTo(parent.start)
                    end.linkTo(parent.end)
                    width = Dimension.fillToConstraints
                }
                .aspectRatio(1f)
                .clip(RoundedCornerShape(8.dp)),
            contentScale = ContentScale.Crop
        )

        if (product.discountPercent > 0) {
            Text(
                text = "-${product.discountPercent}%",
                color = Color.White,
                fontSize = 12.sp,
                fontWeight = FontWeight.Bold,
                modifier = Modifier
                    .constrainAs(badge) {
                        top.linkTo(image.top, margin = 8.dp)
                        end.linkTo(image.end, margin = 8.dp)
                    }
                    .background(Color(0xFFE53935), RoundedCornerShape(4.dp))
                    .padding(horizontal = 6.dp, vertical = 2.dp)
            )
        }

        Text(
            text = product.name,
            fontWeight = FontWeight.SemiBold,
            maxLines = 2,
            overflow = TextOverflow.Ellipsis,
            modifier = Modifier.constrainAs(title) {
                top.linkTo(image.bottom, margin = 8.dp)
                start.linkTo(parent.start)
                end.linkTo(parent.end)
                width = Dimension.fillToConstraints
            }
        )

        Text(
            text = "$${product.salePrice}",
            fontWeight = FontWeight.Bold,
            fontSize = 18.sp,
            modifier = Modifier.constrainAs(price) {
                top.linkTo(title.bottom, margin = 6.dp)
                start.linkTo(parent.start)
            }
        )

        Text(
            text = "$${product.originalPrice}",
            textDecoration = TextDecoration.LineThrough,
            color = MaterialTheme.colorScheme.onSurfaceVariant,
            fontSize = 14.sp,
            modifier = Modifier.constrainAs(originalPrice) {
                baseline.linkTo(price.baseline)
                start.linkTo(price.end, margin = 8.dp)
            }
        )

        IconButton(
            onClick = onAddToCart,
            modifier = Modifier.constrainAs(cartBtn) {
                top.linkTo(price.top)
                bottom.linkTo(price.bottom)
                end.linkTo(parent.end)
            }
        ) {
            Icon(Icons.Default.ShoppingCart, contentDescription = "Add to cart")
        }
    }
}

The baseline alignment between sale price and original price, the badge overlapping the image corner, and the cart button vertically centered against the price — all of that would need multiple nested Box/Row/Column combos.

Common Mistakes

1. Using ConstraintLayout when Row/Column works fine

A simple vertical form doesn't need constraints:

// Overkill
ConstraintLayout {
    val (title, subtitle, button) = createRefs()
    // ...12 lines of constraint wiring for 3 views in a column
}

// Better
Column(modifier = Modifier.padding(16.dp)) {
    Text("Title")
    Text("Subtitle")
    Button(onClick = { }) { Text("Submit") }
}

2. Forgetting Dimension.fillToConstraints

In ConstraintLayout, if you want a view to fill the space between its start and end constraints, you need width = Dimension.fillToConstraints. Without it, the view wraps its content.

3. Nesting Row inside Row inside Column

Three levels of nesting in Compose is a code smell. Step back and consider extracting a composable function or using ConstraintLayout.

4. Hardcoding sizes instead of using weight

// Fragile
Row {
    Text(modifier = Modifier.width(250.dp))
    Button(modifier = Modifier.width(100.dp))
}

// Responsive
Row {
    Text(modifier = Modifier.weight(1f))
    Button(onClick = { }) { Text("Go") }
}

5. Using fillMaxWidth() inside a weighted Row

If a child already has weight, adding fillMaxWidth() does nothing — weight already determines the width.

Performance: Nested vs Flat in Compose

Here's the thing XML developers need to unlearn: nesting in Compose is not the same performance problem as nesting in XML.

XML's LinearLayout inside LinearLayout caused exponential measure/layout passes. Compose's layout system enforces a single-pass measurement. Each composable is measured exactly once.

My guidelines:

1-2 levels of nesting: totally fine
3 levels: consider extracting composables
4+ levels: refactor — either extract or consider ConstraintLayout

I've never profiled a Compose app and found that layout nesting was the bottleneck. If your app is slow, look at recomposition count, image loading, and list performance first.

Quick Decision Guide

Need to stack items vertically?          → Column
Need items side by side?                 → Row
Need to overlay items?                   → Box
Need cross-references between siblings?  → ConstraintLayout
Need barrier-based alignment?            → ConstraintLayout
Need percentage positioning?             → ConstraintLayout
Building a form with aligned labels?     → ConstraintLayout
Everything else?                         → Row + Column + Box

Start simple. Add complexity only when the simpler approach gets awkward.

For setting up navigation between your layout screens, check out the Jetpack Compose Navigation tutorial at https://www.suridevs.com/blog/posts/navigation-component-jetpack-compose-complete-guide/. And if you're structuring ViewModels behind these screens, the MVVM Architecture guide at https://www.suridevs.com/blog/posts/mvvm-jetpack-compose-authentication-guide/ covers the patterns I use in production.

Originally published at SuriDevs

Jetpack Navigation 3 Migration: Type-Safe Routes & Nav2

SuriDevs — Thu, 19 Mar 2026 01:59:09 +0000

I have a production app with four bottom tabs, nine navigation graphs, and 40+ screens. Deep links from push notifications. OAuth callbacks from third-party services. Shared ViewModels across multi-screen flows.

Navigation 2 handled all of this. Messily, with string routes and withArgs hacks, but it worked.

Then I tried migrating to Navigation 3.

The first screen took 20 minutes. The bottom navigation took three days. Deep links? I almost gave up.

Nav3 is genuinely better -- type-safe routes, a visible back stack you actually control, no more NavController black box. But the migration path has gaps that the docs don't warn you about. Shared ViewModels work differently. Deep links are now your problem. Returning results between screens has no built-in solution.

This is everything I learned migrating a production app. The good parts, the painful parts, and the workarounds I wish someone had written down before I started.

What Nav3 Actually Changes

If you've been using Navigation 2, here's the mental shift:

Back stack ownership:
Nav2 — NavController manages everything behind a black box.
Nav3 — You own a SnapshotStateList back stack. Fully visible, fully yours.

Route definitions:
Nav2 — String routes: "project_detail/{projectId}/{projectName}"
Nav3 — Data classes: ProjectDetail(projectId = 42L, projectName = "Alpha")

Screen registration:
Nav2 — NavHost + composable() DSL
Nav3 — NavDisplay + entryProvider

Argument types:
Nav2 — navArgument(type = NavType.LongType)
Nav3 — Just... a Long property on a data class

Reading arguments:
Nav2 — backStackEntry.arguments?.getLong("projectId")
Nav3 — key.projectId

Navigation calls:
Nav2 — navController.navigate(route) / navController.popBackStack()
Nav3 — backStack.add(route) / backStack.removeLastOrNull()

The argument passing alone made the migration worth it. Take a screen that needs a project ID and name. The Nav2 route looked like this:

// Nav2: string route with arguments
"project_detail/{projectId}/{projectName}"

Two navArgument declarations. Two backStackEntry.arguments?.getXxx() calls. One wrong type and you get a runtime crash with an unhelpful error message.

Nav3 equivalent:

// Nav3: just a data class
@Serializable
data class ProjectDetail(
    val projectId: Long,
    val projectName: String
) : NavKey

Compile-time safe. IDE autocomplete. No parsing.

Setting Up Nav3

Dependencies

# gradle/libs.versions.toml

[versions]
nav3 = "1.0.1"
lifecycleNav3 = "2.10.0-rc01"

[libraries]
androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "nav3" }
androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "nav3" }
androidx-lifecycle-viewmodel-nav3 = { module = "androidx.lifecycle:lifecycle-viewmodel-navigation3", version.ref = "lifecycleNav3" }

// app/build.gradle.kts
dependencies {
    implementation(libs.androidx.navigation3.runtime)
    implementation(libs.androidx.navigation3.ui)
    implementation(libs.androidx.lifecycle.viewmodel.nav3)
}

You also need compileSdk = 36 and minSdk = 23. The minSdk bump from 21 caught me off guard -- I had to drop Android 4.x support. Check your analytics first.

Define Your Routes

Every route is now a @Serializable class implementing NavKey. No more string constants.

// navigation/Routes.kt

import androidx.navigation3.runtime.NavKey
import kotlinx.serialization.Serializable

// ---- Bottom tabs ----
@Serializable data object HomeTab : NavKey
@Serializable data object ProjectsTab : NavKey
@Serializable data object MessagesTab : NavKey
@Serializable data object SettingsTab : NavKey

// ---- Auth ----
@Serializable data object Welcome : NavKey
@Serializable data object Login : NavKey
@Serializable data class VerifyOtp(val email: String, val token: String) : NavKey

// ---- Projects ----
@Serializable data class ProjectDetail(
    val projectId: Long,
    val projectName: String
) : NavKey
@Serializable data class TaskDetail(
    val taskId: Long,
    val taskTitle: String,
    val projectId: Long
) : NavKey

Bottom Navigation with Multiple Back Stacks

This is where Nav3 gets interesting -- and where I spent three days.

In Nav2, each bottom tab's back stack was managed invisibly by NavController with saveState/restoreState. In Nav3, you manage each tab's back stack explicitly.

The Navigation State

class AppNavigationState(
    val startTab: NavKey,
    private val _currentTab: MutableState<NavKey>,
    val tabStacks: Map<NavKey, NavBackStack<NavKey>>
) {
    var currentTab: NavKey
        get() = _currentTab.value
        set(value) { _currentTab.value = value }

    val activeStacks: List<NavKey>
        get() = if (currentTab == startTab) {
            listOf(startTab)
        } else {
            listOf(startTab, currentTab)
        }
}

@Composable
fun rememberAppNavigationState(
    startTab: NavKey = HomeTab,
    tabs: Set<NavKey> = setOf(HomeTab, ProjectsTab, MessagesTab, SettingsTab)
): AppNavigationState {
    val currentTab = rememberSaveable { mutableStateOf(startTab) }
    val tabStacks = tabs.associateWith { tab -> rememberNavBackStack(tab) }

    return remember(startTab, tabs) {
        AppNavigationState(
            startTab = startTab,
            _currentTab = currentTab,
            tabStacks = tabStacks
        )
    }
}

The Navigator

class AppNavigator(private val state: AppNavigationState) {

    fun navigateTo(route: NavKey) {
        if (route in state.tabStacks.keys) {
            state.currentTab = route
        } else {
            state.tabStacks[state.currentTab]?.add(route)
        }
    }

    fun goBack(): Boolean {
        val currentStack = state.tabStacks[state.currentTab] ?: return false
        val currentRoute = currentStack.lastOrNull() ?: return false

        // At root of non-start tab? Go back to start tab
        if (currentRoute == state.currentTab && state.currentTab != state.startTab) {
            state.currentTab = state.startTab
            return true
        }

        // At root of start tab? Let the system handle it (exit app)
        if (currentRoute == state.startTab) {
            return false
        }

        currentStack.removeLastOrNull()
        return true
    }

    fun switchTab(tab: NavKey) {
        state.currentTab = tab
    }
}

The Hard Parts (And Workarounds)

1. Deep Links Are Now Your Problem

Nav2 had navDeepLink { uriPattern = "myapp://projects/{projectId}" }. Nav3 has nothing built in. You parse intents yourself and push routes onto the back stack.

object DeepLinkHandler {

    fun handleIntent(intent: Intent, navigator: AppNavigator): Boolean {
        val uri = intent.data ?: return false

        return when {
            uri.pathSegments.firstOrNull() == "projects" -> {
                val projectId = uri.pathSegments.getOrNull(1)?.toLongOrNull() ?: return false
                val projectName = uri.getQueryParameter("name") ?: "Unknown"

                navigator.switchTab(ProjectsTab)
                navigator.navigateTo(ProjectDetail(projectId = projectId, projectName = projectName))
                true
            }
            else -> false
        }
    }
}

2. Returning Results Between Screens

Nav2 had previousBackStackEntry?.savedStateHandle. Nav3 doesn't. Here's the pattern I use:

// 1. Define a result holder
class SelectMemberResult {
    var selectedMemberId: Long? by mutableStateOf(null)
}

// 2. Provide it via CompositionLocal
val LocalSelectMemberResult = staticCompositionLocalOf { SelectMemberResult() }

// 3. In the picker screen, set the result and go back
entry<SelectMemberForTeam> {
    val result = LocalSelectMemberResult.current
    SelectMemberScreen(
        onMemberSelected = { memberId ->
            result.selectedMemberId = memberId
            navigator.goBack()
        }
    )
}

3. Hilt ViewModels

Nav3 + Hilt works, but route arguments no longer appear in SavedStateHandle. You pass them manually:

// DON'T rely on SavedStateHandle for route args in Nav3:
@HiltViewModel
class ProjectDetailViewModel @Inject constructor(
    savedStateHandle: SavedStateHandle  // Empty! No route args here
) : ViewModel()

// DO pass the key directly:
entry<ProjectDetail> { key ->
    val viewModel: ProjectDetailViewModel = hiltViewModel()
    LaunchedEffect(key) {
        viewModel.initialize(key.projectId, key.projectName)
    }
    ProjectDetailScreen(viewModel = viewModel, onBack = { navigator.goBack() })
}

4. Screen Transition Animations

Nav3 has built-in support for transitions, including predictive back gesture animations.

NavDisplay(
    entries = entries,
    onBack = { navigator.goBack() },
    transitionSpec = {
        slideIntoContainer(AnimatedContentTransitionScope.SlideDirection.Start) togetherWith
            slideOutOfContainer(AnimatedContentTransitionScope.SlideDirection.Start)
    },
    popTransitionSpec = {
        slideIntoContainer(AnimatedContentTransitionScope.SlideDirection.End) togetherWith
            slideOutOfContainer(AnimatedContentTransitionScope.SlideDirection.End)
    }
)

Predictive back -- where the previous screen peeks as you swipe -- works out of the box.

The Migration Checklist

If you're migrating from Nav2, here's the order that worked for me:

Add Nav3 dependencies alongside Nav2 -- they don't conflict
Convert route definitions to @Serializable + NavKey data classes
Build NavigationState and Navigator for your bottom tabs
Migrate one tab at a time -- start with the simplest one
Move deep link handling to your own DeepLinkHandler
Convert result-passing screens to CompositionLocal pattern
Remove Nav2 dependencies after all screens are migrated
Test predictive back on every screen

Quick Reference

Nav2                              Nav3
────────────────────────────────────────────────────────
NavHost { }                   →   NavDisplay(entries, onBack)
composable<Route> { }         →   entry<Route> { key -> }
navController.navigate(r)     →   backStack.add(r)
navController.popBackStack()  →   backStack.removeLastOrNull()
NavType.LongType              →   just a Long property
navDeepLink { }               →   manual intent parsing
savedStateHandle result       →   CompositionLocal or shared flow
navigation<Parent> { }       →   gone (use entry decorators)

When NOT to Migrate

Don't migrate if:

Your app uses Fragments or Views -- Nav3 is Compose-only
You depend heavily on nested graph scoping -- still rough in Nav3
You need deep links handled by the framework -- you'll write that yourself
Your team is mid-sprint -- budget a week for 40 screens

Do migrate if:

You're starting a new Compose project
You're tired of runtime crashes from wrong argument types
You want predictive back gestures without extra work
You want to actually see your back stack

Wrapping Up

Nav3 is what Navigation for Compose should have been from the start. The back stack is yours. The routes are type-safe. Arguments are just properties.

For new projects, use Nav3. For existing apps, migrate when you have the bandwidth -- it's worth it, but budget a week, not an afternoon.

For the Nav2 approach with type-safe routes, popUpTo, and nested graphs, check out the Jetpack Compose Navigation tutorial at https://www.suridevs.com/blog/posts/navigation-component-jetpack-compose-complete-guide/. For structuring your ViewModels behind these screens, see the MVVM Architecture guide at https://www.suridevs.com/blog/posts/mvvm-jetpack-compose-authentication-guide/.

Originally published at SuriDevs

Jetpack Compose Navigation Tutorial: Type-Safe Routes & popUpTo

SuriDevs — Mon, 16 Mar 2026 06:17:00 +0000

I'll be honest - navigation in Android has always been a pain. Fragment transactions, back stack bugs, losing state when rotating the screen... I've spent countless hours debugging navigation issues over the years.

When I started using Navigation Component with Jetpack Compose, things got better. Not perfect (we'll get to the gotchas), but definitely better. After implementing navigation across multiple production apps, I wanted to share what actually works - and what doesn't.

Jetpack Compose Navigation Setup

Before anything else, add the navigation-compose dependency to your module-level build.gradle.kts:

dependencies {
    implementation("androidx.navigation:navigation-compose:2.8.9")
}

If you're using version catalogs (libs.versions.toml):

[versions]
navigationCompose = "2.8.9"

[libraries]
androidx-navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigationCompose" }

Then in your build.gradle.kts:

dependencies {
    implementation(libs.androidx.navigation.compose)
}

Sync your project, and you're ready to go. The examples below all use this single dependency.

The Problem with String-Based Routes

If you've worked with Navigation Compose before, you've probably written something like this:

navController.navigate("profile_screen/$userId")

Looks fine, right? Until you typo it as "profil_screen/$userId" somewhere and spend 20 minutes wondering why your app crashes. Ask me how I know.

The fix? Stop using raw strings. I use a sealed class approach that catches these mistakes at compile time:

sealed class AppRoute(val route: String) {
    companion object {
        const val AUTH_GRAPH_PATH = "auth_graph"
        const val MAIN_GRAPH_PATH = "main_graph"
    }

    data object AuthGraph : AppRoute(AUTH_GRAPH_PATH)
    data object MainGraph : AppRoute(MAIN_GRAPH_PATH)

    data object SignIn : AppRoute("$AUTH_GRAPH_PATH/sign_in_screen") {
        const val referralSource = "referralSource"
    }

    data object VerifyCode : AppRoute("$AUTH_GRAPH_PATH/verify_code_screen") {
        const val userEmail = "userEmail"
        const val expirySeconds = "expirySeconds"
    }

    data object Dashboard : AppRoute("$MAIN_GRAPH_PATH/dashboard_screen")
    data object UserProfile : AppRoute("$MAIN_GRAPH_PATH/profile_screen")

    fun withArgs(vararg args: Any?): String {
        return buildString {
            append(route)
            args.forEach { append("/$it") }
        }
    }

    fun withArgsFormat(vararg args: String?): String {
        return buildString {
            append(route)
            args.forEach { append("/{$it}") }
        }
    }
}

Now instead of navController.navigate("profile_screen/$userId"), I write navController.navigate(AppRoute.UserProfile.withArgs(userId)). Typo? Compiler yells at me. Problem solved before it reaches production.

Quick tip: Keep all your routes in a single file. When you have 50+ screens, you'll thank yourself for not having to hunt through the codebase to find route definitions.

Bottom Navigation That Actually Works

Bottom navigation sounds simple until you implement it. The first time I built it, tapping between tabs kept adding screens to the back stack. Users would hit back 15 times trying to exit the app. Embarrassing.

Here's the setup I use now:

sealed class BottomNavItem(
    val route: String,
    @StringRes val labelResId: Int,
    @DrawableRes val iconSelected: Int,
    @DrawableRes val iconUnselected: Int
) {
    data object Home : BottomNavItem(
        route = AppRoute.Dashboard.route,
        labelResId = R.string.tab_home,
        iconSelected = R.drawable.ic_home_filled,
        iconUnselected = R.drawable.ic_home_outline
    )

    data object Search : BottomNavItem(
        route = AppRoute.Search.route,
        labelResId = R.string.tab_search,
        iconSelected = R.drawable.ic_search_filled,
        iconUnselected = R.drawable.ic_search_outline
    )

    data object Favorites : BottomNavItem(
        route = AppRoute.Favorites.route,
        labelResId = R.string.tab_favorites,
        iconSelected = R.drawable.ic_favorite_filled,
        iconUnselected = R.drawable.ic_favorite_outline
    )

    data object Settings : BottomNavItem(
        route = AppRoute.Settings.route,
        labelResId = R.string.tab_settings,
        iconSelected = R.drawable.ic_settings_filled,
        iconUnselected = R.drawable.ic_settings_outline
    )

    companion object {
        val items = listOf(Home, Search, Favorites, Settings)
    }
}

And the actual navigation bar:

@Composable
fun AppBottomBar(
    navController: NavController,
    currentTabIndex: Int,
    onTabSelected: (Int) -> Unit
) {
    Row(
        modifier = Modifier
            .fillMaxWidth()
            .background(MaterialTheme.colorScheme.surface)
            .padding(vertical = 8.dp),
        horizontalArrangement = Arrangement.SpaceEvenly
    ) {
        BottomNavItem.items.forEachIndexed { index, item ->
            val isSelected = currentTabIndex == index

            Box(
                modifier = Modifier
                    .weight(1f)
                    .clickable {
                        onTabSelected(index)
                        navController.navigate(item.route) {
                            popUpTo(navController.graph.findStartDestination().id) {
                                saveState = true
                            }
                            launchSingleTop = true
                            restoreState = true
                        }
                    },
                contentAlignment = Alignment.Center
            ) {
                Column(horizontalAlignment = Alignment.CenterHorizontally) {
                    Icon(
                        painter = painterResource(
                            if (isSelected) item.iconSelected else item.iconUnselected
                        ),
                        contentDescription = stringResource(item.labelResId),
                        tint = if (isSelected)
                            MaterialTheme.colorScheme.primary
                        else
                            MaterialTheme.colorScheme.onSurfaceVariant
                    )

                    if (isSelected) {
                        Text(
                            text = stringResource(item.labelResId),
                            style = MaterialTheme.typography.labelSmall,
                            color = MaterialTheme.colorScheme.primary
                        )
                    }
                }
            }
        }
    }
}

The three flags in the navigate block are crucial - I learned this the hard way:

popUpTo(startDestination) + saveState = true - Without this, every tab switch adds to the back stack AND you lose scroll position
launchSingleTop = true - Prevents duplicate screens when users spam-tap a tab
restoreState = true - Brings back the tab's previous state

Miss any of these and you'll get bug reports. Trust me.

Nested Graphs (How I Organize Large Apps)

When your app grows beyond 10-15 screens, throwing everything into one NavHost becomes a mess. I split navigation by feature:

// Auth module owns its own navigation
fun NavGraphBuilder.authNavGraph(
    navController: NavHostController,
    onAuthComplete: () -> Unit
) {
    navigation(
        route = AppRoute.AuthGraph.route,
        startDestination = AppRoute.Welcome.withArgsFormat(
            AppRoute.Welcome.referralSource
        )
    ) {
        addWelcomeScreen(navController)
        addSignInScreen(navController, onAuthComplete)
        addSignUpScreen(navController)
        addVerifyCodeScreen(navController)
        addResetPasswordScreen(navController, onAuthComplete)
        addForgotPasswordScreen(navController)
    }
}

// Main app module
fun NavGraphBuilder.mainNavGraph(
    navController: NavHostController,
    onSignOut: () -> Unit
) {
    navigation(
        route = AppRoute.MainGraph.route,
        startDestination = AppRoute.Dashboard.route
    ) {
        addDashboardScreen(navController)
        addHomeGraph(navController)
        addSearchGraph(navController)
        addFavoritesGraph(navController)
        addSettingsGraph(navController, onSignOut)
        addDetailsGraph(navController)
        addProfileGraph(navController)
    }
}

Then wire them together:

@Composable
fun RootNavigation(
    navController: NavHostController = rememberNavController(),
    startDestination: String = AppRoute.AuthGraph.route
) {
    NavHost(
        navController = navController,
        startDestination = startDestination
    ) {
        authNavGraph(
            navController = navController,
            onAuthComplete = {
                navController.navigate(AppRoute.MainGraph.route) {
                    popUpTo(AppRoute.AuthGraph.route) { inclusive = true }
                }
            }
        )

        mainNavGraph(
            navController = navController,
            onSignOut = {
                navController.navigate(AppRoute.AuthGraph.route) {
                    popUpTo(AppRoute.MainGraph.route) { inclusive = true }
                }
            }
        )
    }
}

Why I prefer this: Each feature team can work on their navigation independently. The auth team doesn't need to know anything about the settings flow, and vice versa. For how I structure the ViewModel and state management layer behind these screens, check out the MVVM Architecture guide at https://www.suridevs.com/blog/posts/mvvm-jetpack-compose-authentication-guide/.

Adding Screen Transitions

Default navigation has no animations - screens just pop in and out. It feels cheap. I add slide + fade transitions to everything:

private fun NavGraphBuilder.addSignInScreen(
    navController: NavHostController,
    onAuthComplete: () -> Unit
) {
    composable(
        route = AppRoute.SignIn.withArgsFormat(AppRoute.SignIn.referralSource),
        arguments = listOf(
            navArgument(AppRoute.SignIn.referralSource) {
                type = NavType.IntType
                defaultValue = -1
            }
        ),
        enterTransition = {
            slideInHorizontally { it } + fadeIn(tween(400))
        },
        exitTransition = {
            slideOutHorizontally { -it } + fadeOut(tween(400))
        },
        popEnterTransition = {
            slideInHorizontally { -it } + fadeIn(tween(400))
        },
        popExitTransition = {
            slideOutHorizontally { it } + fadeOut(tween(400))
        }
    ) { backStackEntry ->
        val referralSource = backStackEntry.arguments
            ?.getInt(AppRoute.SignIn.referralSource)

        SignInScreen(
            referralSource = referralSource,
            onNavigateBack = { navController.navigateUp() },
            onForgotPassword = {
                navController.navigate(
                    AppRoute.ForgotPassword.withArgs(referralSource)
                )
            },
            onSignUp = {
                navController.navigate(
                    AppRoute.SignUp.withArgs(referralSource)
                )
            },
            onSignInSuccess = onAuthComplete
        )
    }
}

400ms feels right to me - fast enough to not annoy users, slow enough to actually see the transition. I tried 300ms initially but it felt too abrupt.

Gotcha: Don't forget popEnterTransition and popExitTransition. Without them, going back looks weird because the animations don't reverse properly.

Passing Multiple Arguments (The Ugly Part)

This is where Navigation Component gets annoying. Passing one or two arguments is fine. But what about six?

navController.navigate(
    AppRoute.VerifyCode.withArgs(
        userEmail,
        expirySeconds,
        sourceId,
        sessionToken,
        null,  // optional param
        originScreen
    )
)

Yeah, it's a lot of boilerplate. Some people use SafeArgs or custom serialization to clean this up. The newer Navigation 3 API (https://www.suridevs.com/blog/posts/navigation-3-jetpack-compose-migration-guide/) eliminates most of this with type-safe serialization, but if you're on Nav2, I've just accepted the verbosity - it works and it's explicit about what's being passed.

Important: If you're passing complex objects, don't. Pass IDs and fetch the data in the destination screen. Navigation arguments are meant for primitives and simple strings.

Architecture Overview

Here's roughly how the navigation structure looks when everything is connected:

┌─────────────────────────────────────────────────────────┐
│                     MainActivity                        │
│                          │                              │
│                      NavHost                            │
│          ┌───────────────┴───────────────┐              │
│          ▼                               ▼              │
│     AuthGraph                       MainGraph           │
│     ├── Welcome                     ├── Dashboard       │
│     ├── SignIn                      │   ├── HomeGraph   │
│     ├── SignUp                      │   ├── SearchGraph │
│     ├── VerifyCode                  │   ├── Favorites   │
│     ├── ForgotPassword              │   └── Settings    │
│     └── CreatePassword              ├── DetailsGraph    │
│                                     └── ProfileGraph    │
└─────────────────────────────────────────────────────────┘

Deep Linking

If you need to open specific screens from push notifications or external links, add deep links to your composable:

composable(
    route = AppRoute.ItemDetail.withArgsFormat(AppRoute.ItemDetail.itemId),
    arguments = listOf(
        navArgument(AppRoute.ItemDetail.itemId) { type = NavType.StringType }
    ),
    deepLinks = listOf(
        navDeepLink {
            uriPattern = "https://example.com/item/{${AppRoute.ItemDetail.itemId}}"
        },
        navDeepLink {
            uriPattern = "myapp://item/{${AppRoute.ItemDetail.itemId}}"
        }
    )
) { backStackEntry ->
    ItemDetailScreen(
        itemId = backStackEntry.arguments?.getString(AppRoute.ItemDetail.itemId)
    )
}

Don't forget to add the intent filter in your manifest. I've seen people set up deep links in code and wonder why they don't work - the manifest configuration is easy to miss.

Common Mistakes I've Made (So You Don't Have To)

1. Forgetting inclusive = true when clearing back stack

After login, you want to clear the auth screens so users can't go back to them:

navController.navigate(AppRoute.MainGraph.route) {
    popUpTo(AppRoute.AuthGraph.route) { inclusive = true }  // Don't forget this!
}

Without inclusive = true, the Welcome screen stays in the back stack.

2. Not handling configuration changes

If you store navController in a regular variable instead of using rememberNavController(), you'll lose navigation state on rotation.

3. Navigating from non-UI threads

Navigation must happen on the main thread. If you're navigating after an API call, make sure you're on the right dispatcher.

4. Passing large objects as arguments

Just don't. Pass an ID, fetch the data in the destination. I learned this when my app started crashing with TransactionTooLargeException.

Wrapping Up

Navigation Component isn't perfect, but it beats manual Fragment transactions any day. The sealed class approach for routes has saved me from countless typos, and proper back stack handling makes the app feel polished.

If you're starting a new Compose project, set up your navigation structure early. Retrofitting this into an existing app is painful - I've done it twice and don't recommend it.

If you're evaluating whether Compose is the right choice for your project, I wrote about the strengths and weaknesses of Jetpack Compose (https://www.suridevs.com/blog/posts/jetpack-compose-strengths-weaknesses/) from a production perspective. And if you're ready to move to the latest navigation API, check out the Navigation 3 migration guide at https://www.suridevs.com/blog/posts/navigation-3-jetpack-compose-migration-guide/.

Originally published at SuriDevs

Kotlin Coroutines: From Callback Hell to Clean Async Code

SuriDevs — Fri, 13 Mar 2026 05:09:21 +0000

I spent years writing callback-based Android code. Nested callbacks inside callbacks, trying to chain API calls, handling errors at every level. It worked, but reading that code six months later was painful. Coroutines changed that completely.

If you're still on callbacks or RxJava and wondering if coroutines are worth learning - they are. Not because they're new and shiny, but because they make async code look like regular sequential code. That's it. That's the whole pitch.

The Problem Coroutines Solve

Here's what loading data looked like with callbacks in a document scanner app I worked on:

// The callback nightmare - actual pattern from production code
fun processScannedDocument(bitmap: Bitmap) {
    imageProcessor.detectEdges(bitmap, object : Callback<EdgeResult> {
        override fun onSuccess(edges: EdgeResult) {
            imageProcessor.cropToEdges(bitmap, edges, object : Callback<Bitmap> {
                override fun onSuccess(cropped: Bitmap) {
                    imageProcessor.enhanceContrast(cropped, object : Callback<Bitmap> {
                        override fun onSuccess(enhanced: Bitmap) {
                            ocrEngine.extractText(enhanced, object : Callback<String> {
                                override fun onSuccess(text: String) {
                                    runOnUiThread {
                                        showResult(enhanced, text)
                                    }
                                }
                                override fun onError(e: Exception) {
                                    runOnUiThread { showError(e) }
                                }
                            })
                        }
                        override fun onError(e: Exception) {
                            runOnUiThread { showError(e) }
                        }
                    })
                }
                override fun onError(e: Exception) {
                    runOnUiThread { showError(e) }
                }
            })
        }
        override fun onError(e: Exception) {
            runOnUiThread { showError(e) }
        }
    })
}

Four levels deep. Each callback needs its own error handling. The actual business logic - detect edges, crop, enhance, OCR - is buried in ceremony.

Here's the same thing with coroutines:

suspend fun processScannedDocument(bitmap: Bitmap): DocumentResult {
    return try {
        val edges = imageProcessor.detectEdges(bitmap)
        val cropped = imageProcessor.cropToEdges(bitmap, edges)
        val enhanced = imageProcessor.enhanceContrast(cropped)
        val text = ocrEngine.extractText(enhanced)
        DocumentResult.Success(enhanced, text)
    } catch (e: Exception) {
        DocumentResult.Error(e.message ?: "Processing failed")
    }
}

Sequential code that happens to be async. One try-catch handles all errors. The processing pipeline is obvious at a glance.

Suspend Functions - The Building Block

The suspend keyword marks functions that can pause and resume. When you call a suspend function, it doesn't block the thread - it suspends execution, frees the thread for other work, and resumes when the result is ready.

// This doesn't block the main thread
suspend fun calculateExpenseSplit(
    participants: List<Participant>,
    items: List<ExpenseItem>
): SplitResult {
    return withContext(Dispatchers.Default) {
        // Complex calculation happens off main thread
        val individualShares = mutableMapOf<String, Double>()

        items.forEach { item ->
            val sharers = item.sharedBy
            val perPersonCost = item.amount / sharers.size
            sharers.forEach { sharerId ->
                individualShares[sharerId] =
                    (individualShares[sharerId] ?: 0.0) + perPersonCost
            }
        }

        SplitResult(individualShares, calculateSettlements(individualShares))
    }
}

You can only call suspend functions from other suspend functions or from a coroutine scope. The compiler enforces this - try calling a suspend function from a regular function and you'll get an error.

Dispatchers - Where Your Code Runs

This confused me at first. Dispatchers determine which thread pool your coroutine uses:

Dispatchers.Main - The UI thread. Use for updating views, showing dialogs. Never do heavy work here.

Dispatchers.IO - Optimized for blocking IO operations. Network calls, file reads, database queries. Can spin up more threads than CPU cores because these operations spend most time waiting.

Dispatchers.Default - CPU-intensive work. Image processing, complex calculations, parsing large data. Thread count matches CPU cores.

Here's how I use them in a podcast app:

class EpisodeDownloader @Inject constructor(
    private val api: PodcastApi,
    private val storage: EpisodeStorage
) {
    suspend fun downloadEpisode(episode: Episode): DownloadResult {
        return withContext(Dispatchers.IO) {
            try {
                // Download audio file
                val audioBytes = api.downloadAudio(episode.audioUrl)

                // Save to local storage
                val localPath = storage.saveAudioFile(episode.id, audioBytes)

                // Update database
                storage.markAsDownloaded(episode.id, localPath)

                DownloadResult.Success(localPath)
            } catch (e: Exception) {
                DownloadResult.Error(e.message ?: "Download failed")
            }
        }
    }

    suspend fun transcribeEpisode(audioPath: String): String {
        return withContext(Dispatchers.Default) {
            // CPU-heavy transcription work
            transcriptionEngine.processAudio(audioPath)
        }
    }
}

The withContext block switches to the specified dispatcher, does the work, and automatically switches back when done. No manual thread management.

Structured Concurrency - Why It Matters

This feature saves you from memory leaks. Every coroutine runs inside a scope, and when that scope is cancelled, all coroutines inside it get cancelled too.

In Android, you typically use these scopes:

viewModelScope - Tied to ViewModel lifecycle. Cancelled when ViewModel is cleared.

lifecycleScope - Tied to Activity/Fragment lifecycle. Cancelled when destroyed.

class ParkingFinderViewModel @Inject constructor(
    private val parkingRepository: ParkingRepository,
    private val locationProvider: LocationProvider
) : ViewModel() {

    private val _parkingState = MutableStateFlow<ParkingState>(ParkingState.Idle)
    val parkingState: StateFlow<ParkingState> = _parkingState.asStateFlow()

    fun findNearbyParking() {
        // This coroutine automatically cancels if ViewModel is cleared
        viewModelScope.launch {
            _parkingState.value = ParkingState.Searching

            try {
                val location = locationProvider.getCurrentLocation()
                val spots = parkingRepository.findAvailableSpots(
                    latitude = location.latitude,
                    longitude = location.longitude,
                    radiusMeters = 500
                )
                _parkingState.value = ParkingState.Found(spots)
            } catch (e: Exception) {
                _parkingState.value = ParkingState.Error(
                    e.message ?: "Failed to find parking"
                )
            }
        }
    }
}

User navigates away, ViewModel gets cleared, coroutine gets cancelled. No stale location updates, no memory leaks from holding references to destroyed activities.

Parallel Execution with async/await

Sometimes you need multiple things at once. A pet care app might need to load pet profile, upcoming vet appointments, and feeding schedule - all from different sources.

Sequential approach (slow):

// Takes ~3 seconds (1 + 1 + 1)
suspend fun loadPetDashboard(petId: String): PetDashboard {
    val profile = petRepository.getProfile(petId)          // 1 second
    val appointments = vetRepository.getUpcoming(petId)    // 1 second
    val feedingSchedule = scheduleRepository.get(petId)    // 1 second
    return PetDashboard(profile, appointments, feedingSchedule)
}

Parallel approach (fast):

// Takes ~1 second (all run simultaneously)
suspend fun loadPetDashboard(petId: String): PetDashboard = coroutineScope {
    val profile = async { petRepository.getProfile(petId) }
    val appointments = async { vetRepository.getUpcoming(petId) }
    val feedingSchedule = async { scheduleRepository.get(petId) }

    PetDashboard(
        profile = profile.await(),
        appointments = appointments.await(),
        feedingSchedule = feedingSchedule.await()
    )
}

async starts a coroutine that returns a Deferred - basically a promise. await() suspends until the result is ready. The three calls run simultaneously, so total time is the slowest one, not the sum.

That coroutineScope wrapper is important. If any of the async calls fail, it cancels the others and throws the exception. Without it, you might have orphaned coroutines still running after an error.

Exception Handling

Coroutine exception handling has some quirks that bit me early on.

For launch, uncaught exceptions propagate to the parent scope:

viewModelScope.launch {
    throw RuntimeException("Boom")  // Crashes the app
}

For async, exceptions are held until you call await():

viewModelScope.launch {
    val deferred = async { throw RuntimeException("Boom") }
    // Exception thrown here when await() is called
    deferred.await()
}

I always wrap coroutine bodies in try-catch for any operation that can fail:

viewModelScope.launch {
    try {
        val result = riskyOperation()
        handleSuccess(result)
    } catch (e: CancellationException) {
        // Don't catch cancellation - rethrow it
        throw e
    } catch (e: Exception) {
        handleError(e)
    }
}

That CancellationException check is critical. Coroutine cancellation works by throwing CancellationException. If you catch and swallow it, your coroutine won't actually cancel. Always rethrow it.

Timeouts

External services hang sometimes. Users hate waiting forever. Use withTimeout to set limits:

suspend fun checkParkingAvailability(spotId: String): AvailabilityStatus {
    return try {
        withTimeout(5000) {  // 5 seconds max
            parkingApi.checkRealTimeStatus(spotId)
        }
    } catch (e: TimeoutCancellationException) {
        AvailabilityStatus.Unknown  // Fallback on timeout
    }
}

Or withTimeoutOrNull for a cleaner null fallback:

suspend fun checkParkingAvailability(spotId: String): AvailabilityStatus {
    return withTimeoutOrNull(5000) {
        parkingApi.checkRealTimeStatus(spotId)
    } ?: AvailabilityStatus.Unknown
}

I use 10-15 second timeouts for network calls and 30 seconds for file operations. Anything longer and users have already given up.

Flow for Streams of Data

suspend functions return one value. Flow returns multiple values over time - like tracking a delivery or monitoring plant sensor data.

// In repository - emits location updates for a delivery
fun trackDelivery(orderId: String): Flow<DeliveryLocation> = flow {
    while (currentCoroutineContext().isActive) {
        val location = deliveryApi.getCurrentLocation(orderId)
        emit(location)

        if (location.status == DeliveryStatus.DELIVERED) {
            break
        }

        delay(10_000)  // Check every 10 seconds
    }
}

// In ViewModel
class DeliveryTrackingViewModel @Inject constructor(
    private val repository: DeliveryRepository
) : ViewModel() {

    private val _deliveryLocation = MutableStateFlow<DeliveryLocation?>(null)
    val deliveryLocation: StateFlow<DeliveryLocation?> = _deliveryLocation

    fun startTracking(orderId: String) {
        viewModelScope.launch {
            repository.trackDelivery(orderId)
                .catch { e ->
                    // Handle errors without crashing the flow
                    _deliveryLocation.value = null
                }
                .collect { location ->
                    _deliveryLocation.value = location
                }
        }
    }
}

The flow keeps emitting location updates until the delivery is complete or the scope is cancelled.

Cancellation - Making It Work Right

Coroutines are cancellable, but your code needs to cooperate. Long-running operations should check for cancellation:

suspend fun batchProcessPhotos(photos: List<PhotoUri>): List<ProcessedPhoto> {
    return photos.map { photo ->
        // Check if we should stop before processing each photo
        ensureActive()

        withContext(Dispatchers.Default) {
            val bitmap = loadBitmap(photo)
            val resized = resizeBitmap(bitmap, maxWidth = 1080)
            val compressed = compressToJpeg(resized, quality = 85)
            ProcessedPhoto(photo.id, compressed)
        }
    }
}

ensureActive() throws CancellationException if the coroutine was cancelled. Without it, your loop keeps running even after the user navigated away.

For CPU-heavy work, use yield() to give cancellation a chance:

suspend fun analyzeExpensePatterns(
    transactions: List<Transaction>
): SpendingAnalysis {
    return withContext(Dispatchers.Default) {
        val categories = mutableMapOf<String, Double>()

        transactions.forEach { transaction ->
            yield()  // Check for cancellation periodically

            val category = categorizeTransaction(transaction)
            categories[category] = (categories[category] ?: 0.0) + transaction.amount
        }

        SpendingAnalysis(categories, calculateTrends(categories))
    }
}

Testing Coroutines

One of the best things about coroutines - they're testable without waiting for real time. Use runTest from the coroutines test library:

class ParkingFinderViewModelTest {

    @Test
    fun `findNearbyParking updates state with spots on success`() = runTest {
        val fakeRepository = FakeParkingRepository()
        fakeRepository.setSpots(listOf(
            ParkingSpot("1", "Main St Garage", available = true),
            ParkingSpot("2", "Central Lot", available = true)
        ))
        val fakeLocation = FakeLocationProvider(lat = 37.7749, lng = -122.4194)

        val viewModel = ParkingFinderViewModel(fakeRepository, fakeLocation)
        viewModel.findNearbyParking()

        // runTest automatically advances virtual time
        val state = viewModel.parkingState.value
        assertTrue(state is ParkingState.Found)
        assertEquals(2, (state as ParkingState.Found).spots.size)
    }

    @Test
    fun `findNearbyParking shows error when location unavailable`() = runTest {
        val fakeRepository = FakeParkingRepository()
        val fakeLocation = FakeLocationProvider(shouldFail = true)

        val viewModel = ParkingFinderViewModel(fakeRepository, fakeLocation)
        viewModel.findNearbyParking()

        assertTrue(viewModel.parkingState.value is ParkingState.Error)
    }
}

runTest handles virtual time - delays complete instantly, timeouts work correctly, and you don't wait for real time to pass.

Mistakes I Made So You Don't Have To

Using GlobalScope - Just don't. It's not tied to any lifecycle, so those coroutines run forever. Memory leaks guaranteed.

// Don't do this
GlobalScope.launch {
    syncPetData()
}

// Do this instead
viewModelScope.launch {
    syncPetData()
}

Blocking the Main Thread - runBlocking blocks the current thread until complete. On Main thread, that freezes your UI.

// This freezes the UI
fun onScanButtonClick() {
    runBlocking {
        processDocument(bitmap)  // UI frozen until complete
    }
}

// This doesn't
fun onScanButtonClick() {
    viewModelScope.launch {
        processDocument(bitmap)  // UI stays responsive
    }
}

Forgetting withContext for Heavy Work - If you're doing CPU or IO work without specifying a dispatcher, you might be running it on Main.

// This runs on Main thread - blocks UI!
viewModelScope.launch {
    val enhanced = imageProcessor.enhance(bitmap)  // Heavy work on Main
}

// This is correct
viewModelScope.launch {
    val enhanced = withContext(Dispatchers.Default) {
        imageProcessor.enhance(bitmap)
    }
}

Catching CancellationException - If you catch all exceptions, you're breaking cancellation.

// Broken cancellation
try {
    downloadEpisode(episode)
} catch (e: Exception) {
    // CancellationException caught and swallowed - coroutine won't cancel!
    log(e)
}

// Correct
try {
    downloadEpisode(episode)
} catch (e: CancellationException) {
    throw e  // Always rethrow
} catch (e: Exception) {
    log(e)
}

Creating New Scopes Inside Coroutines - This breaks structured concurrency.

// Bad - orphaned scope, not cancelled with parent
viewModelScope.launch {
    CoroutineScope(Dispatchers.IO).launch {
        riskyOperation()  // Keeps running even if viewModel cleared
    }
}

// Good - child coroutine, cancelled with parent
viewModelScope.launch {
    withContext(Dispatchers.IO) {
        riskyOperation()
    }
}

When Not to Use Coroutines

Coroutines aren't always the answer:

Simple synchronous code - If it's not async, don't make it async. Adding coroutines to code that doesn't need them just adds complexity.

One-shot callbacks from libraries - A single callback from a third-party library is fine. You can wrap it with suspendCoroutine, but sometimes the effort isn't worth it for a single call.

When the team doesn't know them - If nobody on the team understands coroutines, introducing them in a critical feature is risky. Train first, then adopt.

Wrapping Up

Coroutines took me a few weeks to really internalize. The mental shift from callbacks to sequential async code was the hardest part. Once that clicked, everything else followed.

Start small - convert one callback-heavy function to suspend and see how it feels. Then gradually expand. The patterns here - dispatchers, structured concurrency, exception handling, cancellation - cover most of what you'll need in production.

The code is cleaner, easier to test, and most importantly, easier to understand when you come back to it months later. That alone makes coroutines worth the learning curve.

DEV Community: SuriDevs

My Compose App Was Showing the Wrong Theme After Restart — Here's the Fix

Start With an Enum, Not a Boolean

Persist With SharedPreferences

ThemeViewModel: Two Writes, Not One

AppTheme: Resolve the Boolean, Build the Scheme

Why Two Color Systems? (The Part Most Tutorials Skip)

MainActivity: Where AppCompatDelegate Lives

The Settings Toggle

Mistakes That Bite in Production

FAQ

My Camera App Was Crashing When Users Mixed HDR + 60 FPS — CameraX Fixed It

The Old Way Was Just Guessing

How Feature Groups Actually Work

What Features Are Available

Building a UI That Doesn't Lie

required vs preferred — Pick the Right One

What to Watch Out For in Production

Dependencies

The Payoff

The Room Migration Mistake That Crashed Every User's App

Raw SQLite vs Room

Setup

The Entity

The DAO

Database Class

ViewModel Integration

Migrations

Mistakes I Made

When Room Isn't the Answer

Advanced MVVM in Jetpack Compose: Search, Pagination & Cross-Module Triggers

The Search Problem Everyone Gets Wrong

Managing State When Things Get Complicated

The UI Side

Cross-Module Communication (The Hard Problem)

Flow Operators Cheat Sheet

Error Handling That Doesn't Annoy Users

Retry with Exponential Backoff

Wrapping Up

Flutter Dio Token Refresh: Fixing the Race Condition Most Tutorials Miss

Step 1: Secure Token Storage

Step 2: The Token Refresh Lock

Step 3: DIO Provider with Interceptors

Don't Forget: Reset on Login

Testing the Race Condition Fix

What We Have Now

What's Next

Checklist Before Moving On

Flutter Riverpod: Loading, Error & Success States Guide

The Three States You Always Need

Common Mistakes Developers Make

The State Class Pattern

Why StateNotifier instead of AsyncValue?

The Notifier Pattern

Wiring the UI

Form Submissions Are a Different Shape

Search With Debounce: When Loading IS the State

Pagination: Loading vs LoadingMore

Blocking vs Non-Blocking Errors

Key Takeaways

FAQ

Change App Language in Android (Jetpack Compose) — Runtime Locale Switch

The Problem With the Old Approach

The New Approach (Android 13+)

Setting Up Resource Folders

The Locale Manager Wrapper

LocaleManager vs AppCompatDelegate

A ViewModel for Language State

A Compose Settings Screen

Handling System Default

RTL Gotcha

Common Mistakes

Testing Tips

Bonus: LocaleConfig for Android 13+

Wrapping Up

R8 optimizedResourceShrinking: Reduce Android APK Size by 50%

What is Android Resource Shrinking?

How R8 optimizedResourceShrinking Works

Why the Old Approach Leaked Resources

Enabling It

`required` vs `preferred` — Pick the Right One