Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

navigation3

Implement navigation in Jetpack Compose using Navigation 3. Use when asked to build state-driven navigation, manage back stacks, scope ViewModels, implement adaptive layouts, or migrate from Navigation Compose.

new-silvermoon · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add new-silvermoon/awesome-android-agent-skills --skill navigation3

About this skill


name: navigation3 description: Implement navigation in Jetpack Compose using Navigation 3. Use when asked to build state-driven navigation, manage back stacks, scope ViewModels, implement adaptive layouts, or migrate from Navigation Compose.

Navigation 3

Overview

Implement state-driven navigation in Jetpack Compose using Navigation 3. Unlike Navigation Compose, Navigation 3 models navigation as application state rather than through a NavController. This skill covers navigation keys, back stack management, ViewModel scoping, entry decorators, adaptive layouts, deep links, animations, state restoration, and testing.

Setup

Add the Navigation 3 dependencies:

// build.gradle.kts
dependencies {

    implementation("androidx.navigation3:navigation3-runtime:1.0.0-alpha08")
    implementation("androidx.navigation3:navigation3-ui:1.0.0-alpha08")

    // Lifecycle integration
    implementation("androidx.lifecycle:lifecycle-viewmodel-navigation3:2.9.2")

    // Serialization
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.1")
}

// Enable serialization plugin
plugins {
    kotlin("plugin.serialization") version "2.2.0"
}

Core Concepts

1. Define Navigation Keys

Navigation destinations are represented by immutable serializable objects.

import kotlinx.serialization.Serializable

@Serializable
data object Home

@Serializable
data class Profile(
    val userId: String
)

@Serializable
data class Product(
    val productId: String,
    val showReviews: Boolean = false
)

@Serializable
data object Settings

Keys become your navigation state.


2. Create the Back Stack

Navigation 3 replaces NavController with a mutable state back stack.

@Composable
fun MyApp() {

    val backStack = remember {
        mutableStateListOf<Any>(Home)
    }

    AppNavDisplay(backStack)
}

3. Create NavDisplay

@Composable
fun AppNavDisplay(
    backStack: SnapshotStateList<Any>
) {

    NavDisplay(
        backStack = backStack,
        onBack = {
            if (backStack.size > 1) {
                backStack.removeLast()
            }
        }
    ) { key ->

        when (key) {

            Home ->
                HomeScreen(
                    onProfileClick = {
                        backStack += Profile(it)
                    }
                )

            is Profile ->
                ProfileScreen(
                    userId = key.userId
                )

            is Product ->
                ProductScreen(
                    productId = key.productId,
                    showReviews = key.showReviews
                )

            Settings ->
                SettingsScreen()
        }
    }
}

Navigation Patterns

Navigate Forward

backStack += Profile("user123")

Navigate Back

backStack.removeLast()

Replace Current Screen

backStack[backStack.lastIndex] = Home

Clear Back Stack

backStack.clear()
backStack += Home

Pop To Root

while (backStack.size > 1) {
    backStack.removeLast()
}

Argument Handling

Retrieve Arguments

Arguments already exist inside the navigation key.

when (val key = currentKey) {

    is Profile -> {
        ProfileScreen(
            userId = key.userId
        )
    }

    is Product -> {
        ProductScreen(
            productId = key.productId
        )
    }
}

Pass IDs, Not Objects

// CORRECT
backStack += Profile(user.id)

// Fetch object inside ViewModel
class ProfileViewModel(
    savedStateHandle: SavedStateHandle,
    repository: UserRepository
) : ViewModel() {

    val profile = savedStateHandle.toRoute<Profile>()

    val user =
        repository.getUser(profile.userId)
}
// INCORRECT

backStack += User(...)
backStack += ProductRepository(...)
backStack += ProductViewModel(...)

ViewModel Integration

Navigation 3 scopes ViewModels using entry decorators.

NavDisplay(

    backStack = backStack,

    entryDecorators = listOf(

        rememberSceneSetupNavEntryDecorator(),

        rememberSavedStateNavEntryDecorator(),

        rememberViewModelStoreNavEntryDecorator()
    )

) { key ->

    // destinations
}

ViewModel Example

class ProfileViewModel(
    savedStateHandle: SavedStateHandle
) : ViewModel() {

    val profile =
        savedStateHandle.toRoute<Profile>()
}

Entry Decorators

Navigation 3 uses decorators to attach lifecycle functionality.

Scene Setup

rememberSceneSetupNavEntryDecorator()

Creates the navigation scene for each entry.

Saved State

rememberSavedStateNavEntryDecorator()

Automatically restores destination state after process recreation.

ViewModel Store

rememberViewModelStoreNavEntryDecorator()

Scopes ViewModels to each navigation entry.


Adaptive Navigation

Navigation 3 integrates with Material Adaptive layouts.

NavDisplay(

    backStack = backStack,

    sceneStrategy = rememberListDetailSceneStrategy()

)

Use adaptive scene strategies to automatically switch between:

  • Single pane (phones)
  • Two pane (tablets)
  • Foldables

Deep Links

Deep links should resolve into navigation keys.

fun handleDeepLink(uri: Uri) {

    val userId =
        uri.lastPathSegment ?: return

    backStack += Profile(userId)
}

Avoid manually constructing route strings.


Animations

Navigation transitions are defined using scene transitions.

NavDisplay(

    backStack = backStack,

    transitionSpec = {

        fadeIn() togetherWith fadeOut()

    }
)

Navigation 3 animation APIs may evolve while in alpha.


State Restoration

Navigation keys are serializable and automatically restored.

val backStack = rememberSaveable(
    saver = navBackStackSaver()
) {
    mut
Read the complete source ↗