Type-Safe Navigation Arguments in Jetpack Compose

By Michael Samuel Naeem · March 8, 2026 · 6 min read

The first time a QA report came back saying "the profile screen crashes when you open it from search," I already knew the shape of the bug before I opened the stack trace: a navigation argument that existed in one call site and not another, discovered at runtime because the route was a string. Type-safe navigation in Jetpack Compose exists to kill that entire class of bug. Instead of building routes like "profile/{userId}?tab={tab}" and hoping every caller assembles the URL correctly, you declare a @Serializable class, and the compiler refuses to let you navigate without the arguments it requires.

That shift — from stringly-typed routes to real Kotlin types — is the single biggest quality-of-life improvement Navigation Compose has shipped, and it's worth understanding beyond the copy-paste sample.

Why string routes rot

String routes look harmless in a demo. The problems show up at scale:

• No compile-time contract. A typo in "detials/{id}" compiles fine and blows up when a user taps the link.
• Manual encoding. You URL-encode arguments by hand, and someone eventually forgets, so a value with a slash or a space corrupts the route.
• Argument drift. You add an optional source argument for analytics, update three of the five call sites, and the other two silently pass nothing.
• Fragile refactors. Rename a destination and you're doing a find-and-replace across strings, with no help from the IDE.

None of these are exotic. I've hit every one of them on shipping apps, and they all trace back to the same root cause: the route is data the compiler can't see into.

Declaring destinations as types

The type-safe API uses kotlinx.serialization. You apply the plugin, then model each destination as an object (no args) or a data class (with args):

@Serializable
object Home

@Serializable
data class Profile(val userId: String, val tab: ProfileTab = ProfileTab.Posts)

@Serializable
data class Article(val slug: String)

The NavHost then keys destinations off those types rather than strings:

NavHost(navController, startDestination = Home) {
    composable<Home> {
        HomeScreen(onOpenProfile = { id -> navController.navigate(Profile(userId = id)) })
    }
    composable<Profile> { backStackEntry ->
        val profile: Profile = backStackEntry.toRoute()
        ProfileScreen(userId = profile.userId, tab = profile.tab)
    }
    composable<Article> { backStackEntry ->
        val article: Article = backStackEntry.toRoute()
        ArticleScreen(slug = article.slug)
    }
}

Two things earn their keep here. navigate(Profile(userId = id)) is a constructor call, so a missing userId is a compile error, not a crash. And backStackEntry.toRoute<Profile>() gives you the deserialized instance with defaults already applied — tab falls back to ProfileTab.Posts without a null check. The whole round trip is typed end to end.

Default values and optionality that actually work

With string routes, "optional argument" meant appending a query parameter and remembering the ?arg={arg} syntax and a nullable = true in the argument list. With serializable routes, optionality is just a Kotlin default value or a nullable property. tab: ProfileTab = ProfileTab.Posts is optional because Kotlin says so, and the library encodes it as a query parameter under the hood. You stop thinking about the URL grammar entirely and think in terms of your data model, which is where the decisions actually belong.

The senior-engineer opinion I'll plant here: pass IDs, not objects. It's tempting to make an entire User @Serializable and shove it into the back stack so the detail screen doesn't refetch. Don't. The back stack gets persisted across process death, so a fat object bloats saved state and goes stale the moment the underlying data changes. Pass the userId, let the destination's ViewModel load fresh data, and treat navigation arguments as the minimum key needed to reconstruct the screen. This pairs naturally with how you already structure state in Kotlin coroutines and Flow patterns — the argument is the query key, the Flow produces the state.

Custom types and NavType

Primitives, enums, and Strings serialize without ceremony. When you genuinely need a custom type in a route — say a small value class — you register a NavType:

val ProfileTabNavType = object : NavType<ProfileTab>(isNullableAllowed = false) {
    override fun get(bundle: Bundle, key: String) =
        bundle.getString(key)?.let(ProfileTab::valueOf)
    override fun parseValue(value: String) = ProfileTab.valueOf(value)
    override fun serializeAsValue(value: ProfileTab) = value.name
    override fun put(bundle: Bundle, key: String, value: ProfileTab) =
        bundle.putString(key, value.name)
}

composable<Profile>(typeMap = mapOf(typeOf<ProfileTab>() to ProfileTabNavType)) { /* ... */ }

Enums are usually handled for you, so this is the escape hatch for the odd case. If you find yourself writing many custom NavTypes, that's a smell — it usually means you're trying to move state through navigation that should live in a repository or shared ViewModel instead.

String routes vs type-safe routes

The only honest cost is the serialization plugin and a slightly steeper first hour. Everything after that is the compiler doing work you used to do in code review.

Deep links without hand-writing patterns

Deep links were the worst part of string routes — you maintained the URI pattern in a second place and prayed it matched the route. With type-safe destinations you attach a navDeepLink and the library derives the mapping from the type, so https://app.example.com/profile/42 resolves straight into Profile(userId = "42"). Keep the argument set small here too; a deep link that requires five arguments is a deep link nobody can construct correctly from the outside.

If you're standing up a fresh navigation graph, it's worth looking at where the whole library is heading with Navigation 3 for Jetpack Compose, which leans even harder into holding the back stack as ordinary typed state you own. The mental model there is the logical extension of what type-safe routes started: navigation is data, and data should be typed.

How I'd adopt it

On a greenfield screen, start type-safe from commit one — there's no reason not to. On an existing app, convert incrementally. String and typed destinations coexist in the same NavHost, so migrate the crash-prone screens first (usually the ones with three-plus arguments), verify deep links still resolve, and delete each string route once its last caller is converted. Budget an afternoon for a medium app, not a sprint.

The payoff isn't cleaner code for its own sake. It's that an entire category of "works on my device, crashes from that entry point" bugs becomes a red squiggle in the editor. That's the trade I'll take every time.

Resources

• Navigation Compose — type safety guide
• Jetpack Navigation overview
• kotlinx.serialization documentation
• Now in Android sample app
• Compose Navigation release notes