compose-navigation

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 4bc96bf96aac · 28 Oct 2026Report an issue or request a re-scan

• Publishernew-silvermoon GitHub userOwner of the repository this skill is read from
• Source foldernew-silvermoon/awesome-android-agent-skills/.github/skills/ui/compose-navigationThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict4bc96bf96aacA new audit runs when the source changes
• Repository statusNot archivedLast push 92 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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.

---
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:

```kotlin
// 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.

```kotlin
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.

```kotlin
@Composable
fun MyApp() {

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

    AppNavDisplay(backStack)
}
```

---

### 3. Create NavDisplay

```kotlin
@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

```kotlin
backStack += Profile("user123")
```

### Navigate Back

```kotlin
backStack.removeLast()
```

### Replace Current Screen

```kotlin
backStack[backStack.lastIndex] = Home
```

### Clear Back Stack

```kotlin
backStack.clear()
backStack += Home
```

### Pop To Root

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

---

## Argument Handling

### Retrieve Arguments

Arguments already exist inside the navigation key.

```kotlin
when (val key = currentKey) {

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

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

### Pass IDs, Not Objects

```kotlin
// 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)
}
```

```kotlin
// INCORRECT

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

---

## ViewModel Integration

Navigation 3 scopes ViewModels using entry decorators.

```kotlin
NavDisplay(

    backStack = backStack,

    entryDecorators = listOf(

        rememberSceneSetupNavEntryDecorator(),

        rememberSavedStateNavEntryDecorator(),

        rememberViewModelStoreNavEntryDecorator()
    )

) { key ->

    // destinations
}
```

### ViewModel Example

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

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

---

## Entry Decorators

Navigation 3 uses decorators to attach lifecycle functionality.

### Scene Setup

```kotlin
rememberSceneSetupNavEntryDecorator()
```

Creates the navigation scene for each entry.

### Saved State

```kotlin
rememberSavedStateNavEntryDecorator()
```

Automatically restores destination state after process recreation.

### ViewModel Store

```kotlin
rememberViewModelStoreNavEntryDecorator()
```

Scopes ViewModels to each navigation entry.

---

## Adaptive Navigation

Navigation 3 integrates with Material Adaptive layouts.

```kotlin
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.

```kotlin
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.

```kotlin
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.

```kotlin
val backStack = rememberSaveable(
    saver = navBackStackSaver()
) {
    mut

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/new-silvermoon/awesome-android-agent-skills
git -C awesome-android-agent-skills checkout 4bc96bf96aac

Works in

1. 2026-10-28
   ✓SAFE B 89 / 100

   first audit · source 4bc96bf96aac

Questions about compose-navigation

• github.com/new-silvermoon/awesome-android-agent-skills/tree/main — the audited source at commit 4bc96bf96aac and every finding aboveObserved · 28 Oct 2026

Spotted something wrong? Report a correction · Methodology