Navigation3 Agent Skill

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.

2k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

910

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/new-silvermoon/awesome-android-agent-skills --skill navigation3

The instruction itself

34 sections, as written by the author

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

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()
        }
    }
}

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.

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()
) {
    mutableStateListOf(Home)
}

Always ensure keys are serializable.

Testing

Navigation becomes simple because it is state-driven.

Example

@Test
fun navigateToProfile() {

    val backStack =
        mutableStateListOf<Any>(Home)

    backStack += Profile("123")

    assertEquals(
        Profile("123"),
        backStack.last()
    )
}

Compose UI tests can verify screen rendering by inspecting the current back stack.

| Navigation Compose | Navigation 3 |

|-------------------|--------------|

| NavController | Mutable back stack |

| NavHost | NavDisplay |

| navigate() | backStack += Key |

| popBackStack() | removeLast() |

| String routes | Serializable keys |

| composable() | when(key) |

| Navigation graph | State-driven destinations |

Recommended Project Structure

navigation/

    AppNavigation.kt

    NavigationKeys.kt

    NavigationDisplay.kt

feature/

    home/

    profile/

    settings/

Critical Rules

DO

Use immutable serializable keys
Keep navigation state inside Compose
Pass IDs instead of complex objects
Scope ViewModels using entry decorators
Use rememberSaveable for state restoration
Model navigation as observable application state

DON'T

Use string routes
Pass repositories or ViewModels through navigation
Mutate navigation keys
Store business objects in the back stack
Recreate the back stack on recomposition
Mix Navigation Compose APIs with Navigation 3 APIs

References

Android Navigation 3 documentation
Navigation 3 samples
Lifecycle ViewModel Navigation 3 documentation
Material 3 Adaptive Navigation documentation

Other skills for the same job

different authors, same section of the catalogue

Theme Factory

by anthropics

vendor ×16

Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.

Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.

Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.

11k tokens scripts

Web Artifacts Builder

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

5k tokens