DEV Community: SuriDevs

Android In-App Updates with Play Core: Complete Guide

SuriDevs — Tue, 26 May 2026 04:58:35 +0000

I shipped a critical bug fix. Two weeks later, 40% of users were still on the broken version. Auto-updates off. They didn't know an update existed.

In-app updates solved this. The prompt shows inside the app — no Play Store hunting required. This guide walks through a production-ready implementation: a sealed-class state model, a StateFlow-based wrapper around Play Core's callback API, a Hilt-injected ViewModel, and the Compose snackbar that asks for the restart. Code samples are real — pulled straight out of a shipping app, not pseudo-code.

What this post covers:

Flexible vs immediate updates — and when to use which
Wiring Play Core into your Gradle build
Modeling the update lifecycle with a sealed class
A StateFlow wrapper around the Play Core callback API
Hilt ViewModel + Activity setup
The restart snackbar (Indefinite duration matters)
Testing without debug build limitations
Gotchas that cost me one-star reviews

The full Play Core in-app updates documentation covers the API surface; this post is about the architecture that makes it work in a real app — including the parts the docs gloss over.

Flexible vs Immediate

There are two in-app update flows, and the choice is yours per call (not per app). Use flexible for everything except security and data-integrity bugs.

	Flexible	Immediate
User experience	App keeps working while update downloads in the background	Full-screen blocking dialog — user can't dismiss or use the app
Download behavior	Downloads in background, snackbar prompts restart when done	Downloads in foreground, installs immediately
When to use	~95% of updates — feature releases, normal bug fixes, version bumps	Security fixes, data corruption bugs, breaking API changes
Dismissal	Returns `RESULT_CANCELED` — let the user keep using the app	Treat as refusal of a critical update; this post calls `finish()`
`updatePriority()` range	Typically priority 0–3 (server-driven)	Typically priority 4–5 (server-driven)

The Play Core API exposes updatePriority() so your server can decide per-release which flow to use without an app update. If you've ever bundled an MVVM-style sealed-class state model into Compose before (see MVVM with Jetpack Compose: authentication guide), the pattern below will feel familiar — same idea, applied to the update lifecycle.

Setup

Add the Play Core KTX library — it handles the coroutines conversion for you:

// libs.versions.toml
[versions]
inAppUpdate = "2.1.0"

[libraries]
play-app-update-ktx = { module = "com.google.android.play:app-update-ktx", version.ref = "inAppUpdate" }

// build.gradle.kts
implementation(libs.play.app.update.ktx)

The KTX variant is what you want — the non-KTX version exposes raw Task callbacks, which you'd just end up wrapping anyway. The official Play Core release notes list versions; 2.1.0 is current as of this writing.

The Update State

I use a sealed class for all the states. The compiler yells at you if you miss one — which is exactly what you want:

sealed class UpdateState {
    data object Idle : UpdateState()
    data object Checking : UpdateState()
    data object Downloaded : UpdateState()
    data object Installing : UpdateState()
    data object Completed : UpdateState()
    data object Failed : UpdateState()
    data object ImmediateFailed : UpdateState()
    data object Cancelled : UpdateState()
    data object NoUpdate : UpdateState()
    data object DownloadingFlexible : UpdateState()
    data class Downloading(val bytesDownloaded: Long, val totalBytes: Long) : UpdateState()
    data class UpdateAvailable(val isImmediate: Boolean, val stalenessDays: Int?, val priority: Int) : UpdateState()
}

ImmediateFailed is separate from Failed — if the user refuses a critical update, you might close the app. General failure is just network issues.

The Update Manager Wrapper

The Play Core API is callback-based and scattered. I wrapped it in a class that exposes a single StateFlow — much easier to work with:

// NOTE: not Hilt-injectable on its own — depends on ComponentActivity,
// which Hilt does not bind by default. Instantiated manually in
// UpdateViewModel.init(activity) below.
class UpdateManagerWrapper(
    context: Context,
    private val activity: ComponentActivity
) {
    private val updateManager = AppUpdateManagerFactory.create(context)

    private val _installStatus = MutableStateFlow<UpdateState>(UpdateState.Idle)
    val installStatus: StateFlow<UpdateState> = _installStatus

    private lateinit var updateLauncher: ActivityResultLauncher<IntentSenderRequest>
    private var installStateListener: InstallStateUpdatedListener? = null
    private var listenerRegistered = false
    private var lastUpdateType: Int? = null

    init {
        // registerForActivityResult must run before the activity reaches
        // STARTED. That's why init() (and therefore this constructor) must
        // be called from MainActivity.onCreate, not onResume or later —
        // see the Activity setup section.
        registerUpdateLauncher()
    }

    private fun registerUpdateLauncher() {
        updateLauncher = activity.registerForActivityResult(
            ActivityResultContracts.StartIntentSenderForResult()
        ) { result ->
            when (result.resultCode) {
                Activity.RESULT_OK -> {
                    if (lastUpdateType == AppUpdateType.IMMEDIATE) {
                        _installStatus.value = UpdateState.Installing
                    } else if (lastUpdateType == AppUpdateType.FLEXIBLE) {
                        _installStatus.value = UpdateState.DownloadingFlexible
                    }
                }
                Activity.RESULT_CANCELED -> {
                    if (lastUpdateType == AppUpdateType.IMMEDIATE) {
                        _installStatus.value = UpdateState.ImmediateFailed
                    } else if (lastUpdateType == AppUpdateType.FLEXIBLE) {
                        _installStatus.value = UpdateState.Cancelled
                    }
                }
                ActivityResult.RESULT_IN_APP_UPDATE_FAILED -> {
                    _installStatus.value = UpdateState.Failed
                }
            }
        }
    }

    fun checkForUpdates() {
        _installStatus.value = UpdateState.Checking

        updateManager.appUpdateInfo.addOnSuccessListener { info ->
            val staleness = info.clientVersionStalenessDays()
            val priority = info.updatePriority()
            val isUpdateAvailable = info.updateAvailability() == UpdateAvailability.UPDATE_AVAILABLE

            if (isUpdateAvailable) {
                when {
                    info.isUpdateTypeAllowed(AppUpdateType.FLEXIBLE) -> {
                        _installStatus.value = UpdateState.UpdateAvailable(false, staleness, priority)
                        startUpdate(info, AppUpdateType.FLEXIBLE)
                        observeFlexibleUpdates()
                    }
                    info.isUpdateTypeAllowed(AppUpdateType.IMMEDIATE) -> {
                        _installStatus.value = UpdateState.UpdateAvailable(true, staleness, priority)
                        startUpdate(info, AppUpdateType.IMMEDIATE)
                    }
                    else -> {
                        _installStatus.value = UpdateState.Idle
                    }
                }
            } else {
                _installStatus.value = UpdateState.NoUpdate
            }
        }.addOnFailureListener {
            _installStatus.value = UpdateState.Failed
        }
    }

    private fun startUpdate(info: AppUpdateInfo, type: Int) {
        lastUpdateType = type
        val options = AppUpdateOptions.newBuilder(type)
            .setAllowAssetPackDeletion(true)
            .build()
        try {
            updateManager.startUpdateFlowForResult(info, updateLauncher, options)
        } catch (e: IntentSender.SendIntentException) {
            _installStatus.value = UpdateState.Failed
        } catch (e: Exception) {
            _installStatus.value = UpdateState.Failed
        }
    }

    private fun observeFlexibleUpdates() {
        if (listenerRegistered) return

        installStateListener = InstallStateUpdatedListener { state ->
            when (state.installStatus()) {
                InstallStatus.DOWNLOADED -> _installStatus.value = UpdateState.Downloaded
                InstallStatus.INSTALLING -> _installStatus.value = UpdateState.Installing
                InstallStatus.INSTALLED -> _installStatus.value = UpdateState.Completed
                InstallStatus.DOWNLOADING -> {
                    _installStatus.value = UpdateState.Downloading(
                        bytesDownloaded = state.bytesDownloaded(),
                        totalBytes = state.totalBytesToDownload()
                    )
                }
                else -> {}
            }
        }
        installStateListener?.let {
            updateManager.registerListener(it)
            listenerRegistered = true
        }
    }

    fun checkForDownloadedUpdateOnResume() {
        updateManager.appUpdateInfo.addOnSuccessListener { info ->
            if (info.updateAvailability() == UpdateAvailability.DEVELOPER_TRIGGERED_UPDATE_IN_PROGRESS) {
                updateManager.startUpdateFlowForResult(
                    info, updateLauncher,
                    AppUpdateOptions.newBuilder(AppUpdateType.IMMEDIATE).build()
                )
            }
            if (info.installStatus() == InstallStatus.DOWNLOADED) {
                _installStatus.value = UpdateState.Downloaded
            }
        }
    }

    fun completeUpdate() {
        updateManager.completeUpdate()
    }

    fun unregisterListener() {
        installStateListener?.let {
            updateManager.unregisterListener(it)
            listenerRegistered = false
            installStateListener = null
        }
    }
}

The listenerRegistered flag prevents duplicate listeners — I've seen apps register the same listener multiple times and wonder why callbacks fire three times.

ViewModel

Nothing fancy here — just connects the wrapper to Compose. SharedFlow for one-off events like "show snackbar now":

@HiltViewModel
class UpdateViewModel @Inject constructor(
    @ApplicationContext private val context: Context
) : ViewModel() {

    private var updateManagerWrapper: UpdateManagerWrapper? = null

    private val _updateState = MutableStateFlow<UpdateState>(UpdateState.Idle)
    val updateState: StateFlow<UpdateState> = _updateState

    private val _eventFlow = MutableSharedFlow<UpdateState>()
    val eventFlow = _eventFlow.asSharedFlow()

    fun init(activity: ComponentActivity) {
        if (updateManagerWrapper == null) {
            updateManagerWrapper = UpdateManagerWrapper(context, activity).also {
                observe(it)
            }
        }
    }

    private fun observe(wrapper: UpdateManagerWrapper) {
        viewModelScope.launch {
            wrapper.installStatus.collect { state ->
                _updateState.value = state
                _eventFlow.emit(state)
            }
        }
    }

    fun checkForUpdates() = updateManagerWrapper?.checkForUpdates()
    fun completeUpdate() = updateManagerWrapper?.completeUpdate()
    fun checkDownloadedOnResume() = updateManagerWrapper?.checkForDownloadedUpdateOnResume()
    fun unregisterListener() = updateManagerWrapper?.unregisterListener()
}

Activity Setup

Call init() and checkForUpdates() early. If user refuses an immediate update, I just close the app — harsh but necessary for critical fixes:

@AndroidEntryPoint
class MainActivity : AppCompatActivity() {
    private val updateViewModel: UpdateViewModel by viewModels()

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

        updateViewModel.init(this)
        updateViewModel.checkForUpdates()

        setContent {
            // Use the SharedFlow (eventFlow) for one-shot side effects like
            // finish(). StateFlow + LaunchedEffect(updateState) would re-fire
            // on every recomposition that re-emits the same state, which is
            // fine for finish() (idempotent) but a classic double-navigation
            // bug for anything else. Use the right tool from the start.
            LaunchedEffect(Unit) {
                updateViewModel.eventFlow.collect { state ->
                    if (state is UpdateState.ImmediateFailed) {
                        finish() // User refused critical update
                    }
                }
            }

            AppContent(
                updateViewModel = updateViewModel,
                onCompleteUpdate = { updateViewModel.completeUpdate() }
            )
        }
    }

    override fun onResume() {
        super.onResume()
        updateViewModel.checkDownloadedOnResume()
    }

    override fun onDestroy() {
        super.onDestroy()
        updateViewModel.unregisterListener()
    }
}

checkDownloadedOnResume() catches downloads that finished while app was backgrounded.

Restart Snackbar

When the download finishes, show a snackbar that sticks around until they tap it:

@Composable
fun MainScreen(
    updateViewModel: UpdateViewModel,
    onCompleteUpdate: () -> Unit
) {
    val snackBarHostState = remember { SnackbarHostState() }

    LaunchedEffect(Unit) {
        updateViewModel.eventFlow.collect { state ->
            if (state is UpdateState.Downloaded) {
                // Dismiss any existing snackbar first — if Downloaded
                // fires twice (e.g., user backgrounds and returns while
                // a download was still completing), we'd otherwise queue
                // a second indefinite snackbar behind the first.
                snackBarHostState.currentSnackbarData?.dismiss()

                // Collect directly inside LaunchedEffect's scope —
                // no need for an inner scope.launch here, which would
                // detach the snackbar from the collector's lifecycle.
                val result = snackBarHostState.showSnackbar(
                    message = "An update has just been downloaded.",
                    actionLabel = "RESTART",
                    duration = SnackbarDuration.Indefinite
                )
                if (result == SnackbarResult.ActionPerformed) {
                    onCompleteUpdate()
                }
            }
        }
    }

    Scaffold(snackbarHost = { SnackbarHost(snackBarHostState) }) { padding ->
        // Screen content
    }
}

SnackbarDuration.Indefinite keeps it visible until they act. Important stuff shouldn't disappear. If you're styling the snackbar to match Material 3 Expressive's motion language, the patterns in Google's Material 3 Expressive in Android 16 apply directly here.

Testing

Can't test with debug builds — Play Store won't return update info for unknown apps. Use Google Play's internal testing track: upload version 1 (e.g., versionCode 10), install it on the device from the test track link, then upload version 2 (versionCode 11) to the same track. When you reopen the installed version, the Play Core API returns an available update and the full flow works end-to-end. Internal testing typically propagates in 5–10 minutes — much faster than production track.

Things I learned the hard way

Users can swipe away the snackbar. Gone. You won't get another chance until they reopen the app. I re-show it when they navigate between screens now.

Don't use immediate updates for small bug fixes. I did this once and got 1-star reviews. Save it for security issues.

Track stalenessDays in your analytics. If most users are 30+ days behind, your update prompts aren't working.

In-app updates aren't magic, but they're better than hoping users randomly check the Play Store. If you're also rethinking how your app handles version-skew at the data layer, the migration patterns in Room database for Android with Kotlin are worth a read — schema changes are the other half of the "users on old versions" problem.

Frequently asked questions

What's the difference between flexible and immediate in-app updates?

Flexible updates download in the background while the user keeps using the app, then prompt for a restart via snackbar — use this 95% of the time. Immediate updates show a full-screen blocking dialog and the user can't proceed until the update installs — reserve this for security fixes or data corruption bugs where running the old version is unsafe. The choice is yours per call, not per app, so you can mix both based on update priority.

Can I test Android in-app updates with debug builds?

No. The Play Store doesn't return update info for apps it doesn't know about, so debug builds always get UpdateAvailability.UPDATE_NOT_AVAILABLE. To test, use Google Play's internal testing track: upload version 1 (e.g., versionCode 10) and install it on the device, then upload version 2 (versionCode 11) to the same track. When you reopen the installed version, the Play Core API returns an available update and the full flow works end-to-end.

What happens if a user dismisses the in-app update prompt?

For flexible updates, the launcher returns RESULT_CANCELED and you should move on silently — the user kept using the app. For immediate updates, dismissal is treated as a refusal of a critical update; in this post we map it to ImmediateFailed and close the app via finish(), but you could also fall back to a flexible update or show a recovery screen. Don't re-prompt aggressively in the same session — that's a one-star-review pattern.

How often should my Android app check for in-app updates?

Once per cold start is the sweet spot — call checkForUpdates() in MainActivity.onCreate() before showing your first screen. Avoid polling on every screen or on every onResume, because the Play Core API hits the network and the launcher result handling gets confusing if multiple checks overlap. For long-lived sessions, also call checkForDownloadedUpdateOnResume() in onResume() so you catch flexible downloads that completed while the app was backgrounded.

Originally published at suridevs.com.

Android ConstraintLayout: Chains, Barriers & Performance

SuriDevs — Fri, 22 May 2026 04:56:57 +0000

Android ConstraintLayout has become the default for everything — and that's the problem. Login screen with three centered fields? ConstraintLayout. Simple vertical list of TextViews? ConstraintLayout. Every extra constraint adds parsing overhead, and most layouts that use it would render identically with a LinearLayout and half the XML.

Here's the honest version: in years of profiling Android UIs, I've never found a 2-level nested LinearLayout to be the bottleneck. ConstraintLayout earns its complexity in specific situations — and this post is about identifying those situations, not making it the default answer to every layout problem.

What this post covers:

How ConstraintLayout works under the hood — why the Cassowary constraint solver lets it flatten 4 levels of LinearLayout into one
Chains, guidelines, barriers, and aspect ratios — what they do and when you actually need them
The match_parent vs 0dp mistake that silently breaks layouts (plus 3 more)
A real product card combining barriers and baseline alignment
Performance: when flat hierarchy actually matters
Should you use it in Jetpack Compose?

The performance angle is real but narrower than people think. A flat hierarchy means fewer measure passes in XML and fewer recomposition scope boundaries in Compose — but the gain only shows up at scale (RecyclerView items, 20+ view screens, low-end devices). For a static screen with eight views, the difference is invisible. The official Android ConstraintLayout documentation covers the API surface; this post is about when the API earns its complexity.

How Android ConstraintLayout Works Under the Hood

The basic idea: instead of nesting layouts inside layouts, you define relationships between views. "This view's top is 16dp below that view's bottom." "This view is centered horizontally in its parent." The layout system solves all these constraints to figure out where everything goes.

Under the hood, it builds a system of linear equations from your constraints and solves them using the Cassowary constraint solver — the same algorithm that powers Apple's Auto Layout. That's why you can express relationships that would be impossible with nested LinearLayouts.

The practical benefit: you get a flat view hierarchy. Instead of 4-5 levels of nested layouts, you have one ConstraintLayout with all your views as direct children. This matters for performance because every level of nesting adds measure/layout passes.

When to Use ConstraintLayout in Android

ConstraintLayout earns its complexity in four specific situations:

Complex cross-axis alignment. When you need to center something vertically while also aligning it to another view's edge horizontally. Try doing that with nested LinearLayouts — it gets ugly fast.
Responsive layouts. Percentage-based sizing, aspect ratios, and bias values let you build layouts that adapt to different screen sizes without writing different XML files.
Replacing deep nesting (especially migrating from RelativeLayout). If you have a layout that's 4+ levels deep with LinearLayout and RelativeLayout — common in older codebases — ConstraintLayout can usually flatten it into a single parent. RelativeLayout-to-ConstraintLayout migration is one of the highest-ROI refactors in legacy Android UIs.
As the base for MotionLayout. MotionLayout extends ConstraintLayout, so any property animation you build with MotionLayout is configured using ConstraintLayout constraints. If animated transitions are on your roadmap, the ConstraintLayout you build today becomes the starting state for tomorrow's MotionScene.

When to Use LinearLayout Instead of ConstraintLayout

Simple vertical stacks. Three TextViews in a column? Use LinearLayout. The constraint syntax just adds noise:

<!-- ConstraintLayout: 12+ lines, IDs required, 4 constraints per view -->
<TextView
    android:id="@+id/title"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintStart_toStartOf="parent" />
<TextView
    android:id="@+id/subtitle"
    app:layout_constraintTop_toBottomOf="@id/title"
    app:layout_constraintStart_toStartOf="parent" />
<!-- ...and so on -->

<!-- LinearLayout: 5 lines, zero IDs needed -->
<LinearLayout android:orientation="vertical">
    <TextView android:text="Title" />
    <TextView android:text="Subtitle" />
    <TextView android:text="Description" />
</LinearLayout>

A bottom sheet with title + body + dismiss button doesn't need 18 constraint attributes. Code review diffs are also easier to read with fewer attributes per view — actual changes stand out instead of getting lost in constraint plumbing.

Simple horizontal rows. A toolbar with an icon and two text labels? LinearLayout with orientation="horizontal" and gravity="center_vertical" is two lines. The same thing in ConstraintLayout needs 9 constraints across 3 views — and you have to remember which view is the "anchor" if you ever reorder them.

Quick prototypes. When you're iterating on a screen layout and don't yet know the final structure, LinearLayout lets you reorder views by cut-and-paste. Reordering in ConstraintLayout means updating constraint references on neighboring views — a small reorder can cascade into 5 attribute edits.

Simple RecyclerView items. Counterintuitively, very simple list items (avatar + text + chevron) can be faster as a LinearLayout because the constraint solver has per-view overhead. ConstraintLayout wins for complex items with 8+ views; for 3-view items it's a wash or slightly slower.

ConstraintLayout Chains, Guidelines, Barriers & Aspect Ratios

Chains

A chain is a bidirectional constraint between two or more views that lets you distribute them along an axis — like flexbox's justify-content, but in XML. When you link views into a chain, the chain's "head" (leftmost or topmost view) controls the distribution style for the whole group. Without chains, you'd have to calculate margins manually or nest a LinearLayout just to space three buttons evenly.

Use chains any time you need views distributed across an axis without hardcoding positions — tab bars, button rows, icon groups.

The three chain styles:

Spread — equal spacing between views. Good for tab bars.
Spread Inside — first and last views touch the edges, others spaced evenly. Good for toolbars with icons at both ends.
Packed — views grouped together, can be positioned with bias. Good for centered button groups.

Example — three buttons spread across the width:

<Button
    android:id="@+id/btn1"
    app:layout_constraintHorizontal_chainStyle="spread"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toStartOf="@id/btn2" />

<Button
    android:id="@+id/btn2"
    app:layout_constraintStart_toEndOf="@id/btn1"
    app:layout_constraintEnd_toStartOf="@id/btn3" />

<Button
    android:id="@+id/btn3"
    app:layout_constraintStart_toEndOf="@id/btn2"
    app:layout_constraintEnd_toEndOf="parent" />

Guidelines

Invisible lines you can constrain to. Useful for consistent alignment across a screen.

<!-- 30% from the left -->
<androidx.constraintlayout.widget.Guideline
    android:id="@+id/guideline"
    android:orientation="vertical"
    app:layout_constraintGuide_percent="0.30" />

<!-- This image stays in the left 30% -->
<ImageView
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toStartOf="@id/guideline" />

Barriers

A Barrier is a virtual boundary that positions itself at the outermost edge of a group of views you specify. Unlike a Guideline (which sits at a fixed position), a Barrier moves at runtime — if one of its referenced views grows because of a longer text string or a different locale, the Barrier shifts to stay outside it.

Use it whenever you have a column of labels with unpredictable lengths and want the adjacent views to always start at a consistent offset — the classic form label + input field pattern.

<!-- Barrier positioned after the longest label -->
<androidx.constraintlayout.widget.Barrier
    android:id="@+id/labelBarrier"
    app:barrierDirection="end"
    app:constraint_referenced_ids="label1,label2,label3" />

<!-- Input field starts after the barrier -->
<EditText
    app:layout_constraintStart_toEndOf="@id/labelBarrier" />

Aspect Ratios

Force a view to maintain proportions:

<ImageView
    android:layout_width="0dp"
    android:layout_height="0dp"
    app:layout_constraintDimensionRatio="16:9"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent" />

The image fills the width and calculates height to maintain 16:9.

4 Layout Mistakes That Break Silently

These four mistakes all compile fine. They don't throw exceptions, they don't show red lines in Android Studio — they just produce layouts that quietly behave wrong. I've shipped each of them at least once.

Using `match_parent` instead of `0dp` (MATCH_CONSTRAINT)

<!-- Wrong - don't use match_parent in ConstraintLayout -->
<TextView
    android:layout_width="match_parent"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent" />

<!-- Right - use 0dp (MATCH_CONSTRAINT) -->
<TextView
    android:layout_width="0dp"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent" />

match_parent doesn't consider constraints. 0dp means "size me based on my constraints."

Missing constraints

Every view needs at least one horizontal and one vertical constraint. If you only constrain the top, the horizontal position is undefined and the view will jump to 0,0.

<!-- Missing horizontal constraint - view position undefined -->
<TextView
    app:layout_constraintTop_toTopOf="parent" />

<!-- Fixed -->
<TextView
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintStart_toStartOf="parent" />

Android Studio shows warnings for this, but they're easy to ignore when you're in a hurry.

Circular dependencies

<!-- These depend on each other - impossible to solve -->
<TextView
    android:id="@+id/text1"
    app:layout_constraintTop_toBottomOf="@id/text2" />

<TextView
    android:id="@+id/text2"
    app:layout_constraintTop_toBottomOf="@id/text1" />

The fix is usually to anchor one view to the parent instead of each other.

Over-constraining (silently dropped attributes)

layout_constraintWidth_percent only takes effect when layout_width="0dp". If you set a fixed width, the percent value is silently ignored — no warning, no error, the layout just doesn't behave the way you expect:

<!-- Wrong - percent attribute is silently ignored because width is fixed -->
<TextView
    android:layout_width="100dp"
    app:layout_constraintWidth_percent="0.5" />

<!-- Right - 0dp width makes percent take effect -->
<TextView
    android:layout_width="0dp"
    app:layout_constraintWidth_percent="0.5"
    app:layout_constraintStart_toStartOf="parent" />

The same rule applies to layout_constraintWidth_default="spread", layout_constraintWidth_min, and layout_constraintWidth_max — they all require layout_width="0dp" to do anything.

Android ConstraintLayout Example: Product Card with Barrier

Here's a product card that uses several ConstraintLayout features:

<androidx.constraintlayout.widget.ConstraintLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:padding="12dp">

    <!-- Square product image - width fills parent, height derived from W,1:1 ratio -->
    <ImageView
        android:id="@+id/productImage"
        android:layout_width="0dp"
        android:layout_height="0dp"
        app:layout_constraintDimensionRatio="W,1:1"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent" />

    <!-- Title below image -->
    <TextView
        android:id="@+id/productTitle"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:layout_marginTop="8dp"
        android:maxLines="2"
        app:layout_constraintTop_toBottomOf="@id/productImage"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent" />

    <!-- Sale price -->
    <TextView
        android:id="@+id/salePrice"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginTop="4dp"
        android:textStyle="bold"
        app:layout_constraintTop_toBottomOf="@id/productTitle"
        app:layout_constraintStart_toStartOf="parent" />

    <!-- Original price (baseline aligned with sale price) -->
    <TextView
        android:id="@+id/originalPrice"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginStart="8dp"
        app:layout_constraintBaseline_toBaselineOf="@id/salePrice"
        app:layout_constraintStart_toEndOf="@id/salePrice" />

    <!-- Barrier sits at the end of whichever price text is wider -->
    <androidx.constraintlayout.widget.Barrier
        android:id="@+id/priceBarrier"
        app:barrierDirection="end"
        app:constraint_referenced_ids="salePrice,originalPrice" />

    <!-- Add to cart button starts AFTER the barrier - never overlaps the prices -->
    <Button
        android:id="@+id/addToCartButton"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Add"
        android:layout_marginStart="8dp"
        app:layout_constraintBaseline_toBaselineOf="@id/salePrice"
        app:layout_constraintStart_toEndOf="@id/priceBarrier"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintHorizontal_bias="1.0" />

</androidx.constraintlayout.widget.ConstraintLayout>

What's happening here:

dimensionRatio="W,1:1" keeps the image square — width fills the parent, height is derived from width. The W, prefix tells the solver which dimension drives the ratio when both are 0dp.
constraintBaseline_toBaselineOf aligns the sale price, original price, and button text on the same text baseline — looks better than top-aligning views with different text sizes.
The Barrier sits at the right edge of whichever price text is wider, and the button's constraintStart_toEndOf="@id/priceBarrier" ties the button's left edge to it. So when "Original Price" is longer than "Sale Price" (or vice versa), the button shifts automatically — no overlap, no manual width calculations.

This would require 3-4 nested layouts without ConstraintLayout.

The Performance Tradeoff: When Flat Hierarchy Actually Matters

In years of profiling Android apps, I've never found a 2-level nested LinearLayout to be the bottleneck. If your frame times are bad, the cause is almost always something else — overdraw, expensive onMeasure in a custom view, large bitmaps being decoded on the main thread, or recomposition storms in Compose.

That said, the flat-hierarchy benefit is real in specific situations:

Where it actually moves the needle:

RecyclerView items inflated thousands of times — saving 0.2ms per item adds up when you scroll a 1,000-row list
Complex screens on low-end devices — weaker CPUs feel every extra measure pass
Layouts with 20+ views — measure/layout complexity is roughly O(n × depth), and depth dominates

Where it doesn't:

Screens with under 10 views
Loading screens, splash screens, anything users see briefly
High-end devices where rendering budget is generous

Run a Layout Inspector trace before you refactor. Don't flatten every LinearLayout speculatively — measure first, find the slow screen, then rewrite that one.

Should You Use ConstraintLayout in Jetpack Compose?

Compose has its own ConstraintLayout implementation. The syntax is different but the concepts are the same:

ConstraintLayout(modifier = Modifier.fillMaxSize()) {
    val (image, title, subtitle) = createRefs()

    Image(
        painter = painterResource(id = R.drawable.product_placeholder),
        contentDescription = null,
        modifier = Modifier.constrainAs(image) {
            top.linkTo(parent.top)
            start.linkTo(parent.start)
        }
    )

    Text(
        text = "Product title",
        modifier = Modifier.constrainAs(title) {
            top.linkTo(image.bottom, margin = 8.dp)
            start.linkTo(parent.start)
        }
    )

    Text(
        text = "Subtitle goes here",
        modifier = Modifier.constrainAs(subtitle) {
            top.linkTo(title.bottom, margin = 4.dp)
            start.linkTo(parent.start)
        }
    )
}

Honestly, I rarely reach for it in Compose. Box, Row, and Column handle 90% of layouts cleanly. The cases where I do use ConstraintLayout in Compose:

Baseline-aligning text across composables that don't share a Row. Inside a single Row you can use Modifier.alignByBaseline() or Modifier.alignBy(FirstBaseline) to baseline-align children. The harder case is aligning text baselines across composables in different parents — say, a Text in one section and a Button label two rows down. That's where ConstraintLayout's linkTo(other.baseline) is the cleanest fix.
Percentage-based positioning using Guideline. Compose has no built-in equivalent — there's Modifier.fillMaxWidth(0.6f) for sizing, but positioning "30% from the start" requires either BoxWithConstraints math or a ConstraintLayout with a vertical guideline.
Sizing relative to the widest of a group. Equivalent to XML Barrier. Useful for label columns where each label has a different length but you want all the input fields to start at the same x-position.

For everything else, nesting Box and Column is clearer than wiring up constraint references. Compose's single-pass measurement system also weakens the performance argument that justifies ConstraintLayout in XML. See Row, Column, Box, and ConstraintLayout compared in Jetpack Compose for a side-by-side breakdown of when each one wins.

The Decision Rule: When Complexity Pays Off

Reach for ConstraintLayout when you find yourself doing one of these:

Nesting 3+ levels of LinearLayout or FrameLayout
Baseline-aligning text across views of different types
Percentage-based positioning (e.g. "title sits in the left 60% of the screen")
Building a layout that needs to react to the longest item in a group (Barrier)

For everything else, start with LinearLayout — or Row/Column in Compose — and only switch when the simpler layout actually fights you.

Try this on your current project right now: open the screen with the most nesting in Layout Inspector. Count the depth. If anything's at 4+ levels, that's a candidate for flattening with ConstraintLayout. Most Android codebases have exactly one or two screens that genuinely need it — not every screen, not most screens.

The goal isn't to use ConstraintLayout everywhere. It's to recognize the specific situations where it earns the complexity, and keep everything else simple.

FAQ

When should I use ConstraintLayout instead of LinearLayout?

Use ConstraintLayout when your layout needs cross-axis alignment, percentage-based sizing, or you're already at 3+ levels of nesting. For simple vertical stacks or basic horizontal rows, LinearLayout is less code and just as fast. The complexity of ConstraintLayout only pays off when the problem actually requires it — which is maybe 20-30% of screens in a typical app.

What is a Barrier in ConstraintLayout?

A Barrier is a virtual view that dynamically tracks the outermost edge of a group of views. You reference multiple views by ID, set a direction (start, end, top, bottom), and the Barrier positions itself just outside whichever view extends furthest in that direction. It solves the "form labels of different lengths" problem cleanly — input fields constrain to the Barrier, so they always start at the same x-position regardless of how long each label is.

Does ConstraintLayout improve Android app performance?

It can, but the gains are narrower than the docs suggest. A flat view hierarchy reduces measure passes, which helps on complex screens with 20+ views, low-end devices, or RecyclerView items inflated thousands of times. For a simple screen with eight views on a mid-range device, the difference is unmeasurable. Profile first with Layout Inspector — don't refactor every screen speculatively based on the assumption that flat is always faster.

Should I use ConstraintLayout in Jetpack Compose?

Only for specific cases. Compose's Box, Row, and Column handle the vast majority of layouts, and Compose's single-pass measurement already removes the nesting-penalty that makes ConstraintLayout worthwhile in XML. Reach for it in Compose when you need cross-composable baseline alignment, a percentage-based Guideline, or a Barrier equivalent for sizing views relative to the widest in a group. For everything else, nested composables are clearer and easier to maintain.

Originally published at suridevs.com.

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

DEV Community: SuriDevs

Android In-App Updates with Play Core: Complete Guide

Flexible vs Immediate

Setup

The Update State

The Update Manager Wrapper

ViewModel

Activity Setup

Restart Snackbar

Testing

Things I learned the hard way

Frequently asked questions

Android ConstraintLayout: Chains, Barriers & Performance

How Android ConstraintLayout Works Under the Hood

When to Use ConstraintLayout in Android

When to Use LinearLayout Instead of ConstraintLayout

ConstraintLayout Chains, Guidelines, Barriers & Aspect Ratios

Chains

Guidelines

Barriers

Aspect Ratios

4 Layout Mistakes That Break Silently

Using match_parent instead of 0dp (MATCH_CONSTRAINT)

Missing constraints

Circular dependencies

Over-constraining (silently dropped attributes)

Android ConstraintLayout Example: Product Card with Barrier

The Performance Tradeoff: When Flat Hierarchy Actually Matters

Should You Use ConstraintLayout in Jetpack Compose?

The Decision Rule: When Complexity Pays Off

FAQ

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

Using `match_parent` instead of `0dp` (MATCH_CONSTRAINT)

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