--- name: navigation-3 description: Learn how to install and migrate to Jetpack Navigation 3, and how to implement features and patterns such as deep links, multiple backstacks, scenes (dialogs, bottom sheets, list-detail, two-pane, supporting pane), conditional navigation (such as logged-in navigation vs anonymous), returning results from flows, integration with Hilt, ViewModel, Kotlin, and view interoperability. license: Complete terms in LICENSE.txt metadata: author: Google LLC last-updated: '2026-05-05' keywords: - recipe - Android - Navigation 2 - Navigation 3 - migration - Compose - guide - dependencies - NavKey - NavHost - NavDisplay - BottomSheet - list-detail - scenes - two-pane - supporting pane - multiple backstacks - dialog - Hilt - ViewModel - View interop. --- ## ROUTING | User signal | Read | |-------------|------| | Migrating from Navigation 2 to Navigation 3 | → Migration guide | | Using string-based routes, needs type-safe first | → Type-safe destinations guide (Requirements) | | New to Nav3, wants basic NavHost + NavDisplay | → Recipes / Basic API usage | | Bottom nav bar with per-tab back stacks | → Recipes / Common UI | | Deep links from notifications / URIs | → Recipes / Deep links | | Dialogs, bottom sheets, list-detail, two-pane | → Recipes / Scenes | | Phone↔tablet adaptive layouts | → Recipes / Material Adaptive | | Custom transitions between destinations | → Recipes / Animations | | Back stack predictive back / pop-to behaviors | → Recipes / Common back stack behavior | | Login-gated vs anonymous flows | → Recipes / Conditional navigation | | Returning results from a flow | → Recipes / Returning results | | Hilt + ViewModel scoping per destination | → Recipes / Working with ViewModel | | Mixing Nav3 with legacy Views | → Recipes / Architecture | ## Migration guide - *[Navigation 2 to Navigation 3 migration guide](references/android/guide/navigation/navigation-3/migration-guide.md)*: Step-by-step guide to migrate an Android application from Navigation 2 to Navigation 3, covering dependency updates, route changes, state management, and UI component replacements. ### Requirements - *[Guide: Migrate to type-safe navigation in Compose](references/android/guide/navigation/type-safe-destinations.md)* : Step-by-step guide to migrating an Android application from string-based navigation to **Type-Safe Navigation** in Jetpack Compose using Jetpack Navigation 2. ## Developer documentation - \*[Navigation 3](references/android/guide/navigation/navigation-3/index.md). Search documentation for more information on basics, saving and managing navigation state, modularizing navigation code, creating custom layouts using Scenes, animating between destinations, or applying logic or wrappers to destinations. ## Recipes Code examples showcasing common patterns. ### Basic API usage - *[Basic](references/android/guide/navigation/navigation-3/recipes/basic.md)*: Shows most basic API usage. - *[Saveable back stack](references/android/guide/navigation/navigation-3/recipes/basicsaveable.md)*: Shows basic API usage with a persistent back stack. - *[Entry provider DSL](references/android/guide/navigation/navigation-3/recipes/basicdsl.md)*: Shows basic API usage using the entryProvider DSL. ### Common UI - *[Common UI](references/android/guide/navigation/navigation-3/recipes/common-ui.md)*: Demonstrates how to implement a common navigation UI pattern with a bottom navigation bar and multiple back stacks, where each tab in the navigation bar has its own navigation history. ### Deep links - *[Basic](references/android/guide/navigation/navigation-3/recipes/deeplinks-basic.md)*: Shows how to parse a deep link URL from an Android Intent into a navigation key. - *[Advanced](references/android/guide/navigation/navigation-3/recipes/deeplinks-advanced.md)*: Shows how to handle deep links with a synthetic back stack and correct "Up" navigation behavior. ### Scenes #### Use built-in Scenes - *[Dialog](references/android/guide/navigation/navigation-3/recipes/dialog.md)*: Shows how to create a Dialog. #### Create custom Scenes - *[BottomSheet](references/android/guide/navigation/navigation-3/recipes/bottomsheet.md)*: Shows how to create a BottomSheet destination. - *[List-Detail Scene](references/android/guide/navigation/navigation-3/recipes/scenes-listdetail.md)*: Demonstrates how to implement adaptive list-detail layouts using the Navigation 3 Scenes API. - *[Two pane Scene](references/android/guide/navigation/navigation-3/recipes/scenes-twopane.md)*: Demonstrates how to implement adaptive two-pane layouts using the Navigation 3 Scenes API. ### Material Adaptive - *[Material List-Detail](references/android/guide/navigation/navigation-3/recipes/material-listdetail.md)*: Demonstrates how to implement an adaptive list-detail layout using Material 3 Adaptive. - *[Material Supporting Pane](references/android/guide/navigation/navigation-3/recipes/material-supportingpane.md)*: Demonstrates how to implement an adaptive supporting pane layout using Material 3 Adaptive. ### Animations - *[Animations](references/android/guide/navigation/navigation-3/recipes/animations.md)*: Shows how to override the default animations for all destinations and a single destination. ### Common back stack behavior - *[Multiple back stacks](references/android/guide/navigation/navigation-3/recipes/multiple-backstacks.md)*: Shows how to create multiple top level routes, each with its own back stack. Top level routes are displayed in a navigation bar allowing users to switch between them. State is retained for each top level route, and the navigation state persists config changes and process death. ### Conditional navigation - *[Conditional navigation](references/android/guide/navigation/navigation-3/recipes/conditional.md)*: Switch to a different navigation flow when a condition is met. For example, for authentication or first-time user onboarding. ### Architecture - *[Modularized navigation code (Hilt)](references/android/guide/navigation/navigation-3/recipes/modular-hilt.md)*: Demonstrates how to decouple navigation code into separate modules using Hilt or Dagger for DI. - *[Modularized navigation code (Koin)](references/android/guide/navigation/navigation-3/recipes/modular-koin.md)*: Demonstrates how to decouple navigation code into separate modules using Koin for DI. ### Working with ViewModel #### Passing navigation arguments - *[Basic ViewModel](references/android/guide/navigation/navigation-3/recipes/passingarguments.md)* : Navigation arguments are passed to a `ViewModel` constructed using `viewModel()` ### Returning results - *[Returning Results as Events](references/android/guide/navigation/navigation-3/recipes/results-event.md)* : Returning results as events to content in another `NavEntry` - *[Returning Results as State](references/android/guide/navigation/navigation-3/recipes/results-state.md)* : Returning results as state stored in a `CompositionLocal` ## Automated / AI-Assisted Testing Tooling (local baseline) Use the currently available local toolchain for automation-first Android validation: - Primary tools available: `adb`, `emulator`, repo `./gradlew` / `./gradlew.bat`, `java`, `python3`, `node`, `npm`, `bun`, `aapt`, `aapt2`, `gh` - Commonly referenced but currently unavailable in PATH: `android` CLI binary, `sdkmanager`, `avdmanager`, `maestro`, `apkanalyzer`, `bundletool` Recommended unattended validation loop: 1. Run deterministic gates each iteration: - `:core:test`, `:app:test`, `:app:assembleDebug`, `:app:lint` 2. If a device is present (`adb devices`), run connected instrumentation: - `:app:connectedDebugAndroidTest` 3. Persist per-iteration logs and summaries under `.sisyphus/evidence/`. 4. Bucket failures by signature (for flaky analysis), especially: - `ComposeTimeoutException` - `No compose hierarchies found` - device transport errors (`No connected devices`, `device ... not found`) For managed devices where keep-awake cannot be enabled, use a sleep-tolerant loop: - continue non-device gates every cycle - classify connected runs as `PASS` / `FAIL` / `SKIP(no-device)` - avoid treating temporary device sleep as total run failure.