# nav3-recipes

**Repository Path**: mirrors_android/nav3-recipes

## Basic Information

- **Project Name**: nav3-recipes
- **Description**: Implement common use cases with Jetpack Navigation 3
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-22
- **Last Updated**: 2026-09-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Navigation 3 - Code recipes
[Jetpack Navigation 3](https://goo.gle/nav3) is a library for app navigation. This repository contains recipes for how to
use its APIs to implement common navigation use cases. Each recipe introduces a single concept. Instead
of making existing recipes more complex, there should be a new recipe for that particular concept.

Every Navigation 3 release will be an opportunity for patterns you see in recipes to "graduate" and become
(optional) helpers in the library itself. Then we'll update the recipe to use that prebuilt helper, thus
ensuring that the recipes continue to be a good way to approach these kinds of problems.

Recipes on the `main` branch use the **latest** (which may be an alpha or snapshot) version of Nav3. For recipes that use **stable** versions, check the [releases page](https://github.com/android/nav3-recipes/releases).

## Recipes
These are the recipes and what they demonstrate.

### Basic API usage
- **[Basic](app/src/main/java/com/example/nav3recipes/basic)**: Shows most basic API usage.
- **[Saveable back stack](app/src/main/java/com/example/nav3recipes/basicsaveable)**: As above, with a persistent back stack.
- **[Parcelable back stack](app/src/main/java/com/example/nav3recipes/basicparcelable)**: As above, but with a persistent back stack of `Parcelable` routes.
- **[Entry provider DSL](app/src/main/java/com/example/nav3recipes/basicdsl)**: As above, using the entryProvider DSL.
- **[Lifecycle Owner](app/src/main/java/com/example/nav3recipes/lifecycleowner)**: Shows how to observe and use `LocalLifecycleOwner` within entry content.

### Deep links
Read the [guide to deeplinking](docs/deeplink-guide.md).
- **[Static Uri](/app/src/main/java/com/example/nav3recipes/deeplink/handlerequests/staticuri)**: Shows how to handle deep links with a static Uri using `UriDeepLinkMatcher`.
- **[Uri with Arguments](/app/src/main/java/com/example/nav3recipes/deeplink/handlerequests/uriarguments)**: Shows how to handle deep link with uri arguments using `UriDeepLinkMatcher`.
- **[Synthetic BackStack](/app/src/main/java/com/example/nav3recipes/deeplink/handlerequests/syntheticbackstack)**: Shows how to deep link between apps with a synthetic back stack using `DeepLinkMatcher.withBackStack` and correct "Up" navigation behavior.
- **[Custom DeepLinkMatcher](/app/src/main/java/com/example/nav3recipes/deeplink/usecases/matcher)**: Demonstrates how to create a custom `DeepLinkMatcher` to parse deep links from `DeepLinkRequest` extras.
- **[Uri with Non-Primitive Arguments](/app/src/main/java/com/example/nav3recipes/deeplink/usecases/serializer)**: Demonstrates how to use a custom `DeepLinkSerializer` for URI deep link keys with non-primitive arguments.
- **[Composite DeepLink Filters](/app/src/main/java/com/example/nav3recipes/deeplink/usecases/filter)**: Demonstrates how to combine multiple `DeepLinkMatcher.Filter` instances using infix functions (`and`, `or`).

### Scenes
#### Use built-in Scenes
- **[Dialog](app/src/main/java/com/example/nav3recipes/dialog)**: Shows how to create a Dialog.

#### Create custom Scenes
- **[BottomSheet](app/src/main/java/com/example/nav3recipes/bottomsheet)**: Shows how to create a BottomSheet destination.
- **[List-Detail Scene](app/src/main/java/com/example/nav3recipes/scenes/listdetail)**: Shows how to create a custom, list-detail layout using a `Scene` and `SceneStrategy` (see video of UI behavior below).
- **[Two pane Scene](app/src/main/java/com/example/nav3recipes/scenes/twopane)**: Shows how to create a custom, 2-pane layout.

#### Use Material Scenes
Examples showing how to use the layouts provided by the [Compose Material3 Adaptive Navigation3 library](https://developer.android.com/jetpack/androidx/releases/compose-material3-adaptive#compose_material3_adaptive_navigation3_version_10_2)
- **[List-Detail](app/src/main/java/com/example/nav3recipes/material/listdetail)**: Shows how to use a Material adaptive list-detail layout.
- **[Supporting Pane](app/src/main/java/com/example/nav3recipes/material/supportingpane)**: Shows how to use a Material adaptive supporting pane layout.

Note: If you find a bug or have a feature request for Material3 Adaptive Scenes [please file it here](https://issuetracker.google.com/issues/new?component=1467081). Don't file an issue on this repository.

### Scene Decorators
- **[Dialog Scene Decorator](app/src/main/java/com/example/nav3recipes/dialogscenedecorator)**: Shows how to use a `DialogSceneDecoratorStrategy` to display a scene in a dialog.
- **[Responsive Navigation Scene Decorator](app/src/main/java/com/example/nav3recipes/navscenedecorator)**: Demonstrates how to add UI elements such as top app bars and navigation bars or rails using the scene decorator API.

### Animations
- **[Animations](app/src/main/java/com/example/nav3recipes/animations)**: Shows how to override the default animations for all destinations and a single destination.
- **[Conditional transitions](app/src/main/java/com/example/nav3recipes/conditionaltransitions)**: Demonstrates how to conditionally select slide transition directions based on pairs of initial and target navigation keys.

### Common back stack behavior
- **[Common navigation UI](app/src/main/java/com/example/nav3recipes/commonui)**: A common navigation toolbar where each item in the toolbar navigates to a top level destination.
- **[Multiple back stacks](app/src/main/java/com/example/nav3recipes/multiplestacks)**: 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](app/src/main/java/com/example/nav3recipes/conditional)**: Switch to a different navigation flow when a condition is met. For example, for authentication or first-time user onboarding.

### Architecture
- **[Hilt - Modularized navigation code](app/src/main/java/com/example/nav3recipes/modular/hilt)**: Demonstrates how to decouple navigation code into separate modules (uses Dagger/Hilt for DI).
- **[Koin - Modularized navigation code](app/src/main/java/com/example/nav3recipes/modular/koin)**: Demonstrates how to decouple navigation code into separate modules (uses Koin for DI).
- **[Metro - Modularized navigation code](metroapp/src/main/java/com/example/nav3recipes/modular/metro)**: Demonstrates how to decouple navigation code into separate modules (uses Metro for DI).
- **[Dynamic feature navigation](app/src/main/java/com/example/nav3recipes/dynamicfeature)**: Demonstrates how to integrate navigation code with Dynamic Feature Module.

### Working with ViewModels
#### Passing navigation arguments
- **[Basic ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/basic)**: Navigation arguments are passed to a ViewModel constructed using `viewModel()`
- **[Hilt injected ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/hilt)**: Navigation arguments are passed to a ViewModel constructed using `hiltViewModel()`
- **[Koin injected ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin)**: Navigation arguments are passed to a ViewModel constructed using `koinViewModel()`
- **[Metro injected ViewModel](metroapp/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/metro)**: Navigation arguments are passed to a ViewModel constructed using `assistedMetroViewModel()`

#### Sharing a ViewModel between screens
- **[Shared ViewModel](app/src/main/java/com/example/nav3recipes/sharedviewmodel)**: Demonstrates how to share a `ViewModel` between different screens (entries) in Navigation 3 using a custom `NavEntryDecorator`.

### Retain
- **[Retain Values for Composables on the Back Stack](app/src/main/java/com/example/nav3recipes/retain)**: Demonstrates how to set up `retain` to persist values as their UI is hidden while on the back stack, and how to implement a custom NavEntryDecorator

### Returning Results
- **[Returning Results as Events](app/src/main/java/com/example/nav3recipes/results/event)**: Returning results as events to content in another NavEntry.
- **[Returning Results as State](app/src/main/java/com/example/nav3recipes/results/state)**: Returning results as state stored in a CompositionLocal.
- **[Returning Results as Serializable State](app/src/main/java/com/example/nav3recipes/results/serializable)**: Returning results as state that survives configuration changes and process death using Kotlin Serialization.

### Interop
- **[Fragment and View Interop](app/src/main/java/com/example/nav3recipes/interop)**: Demonstrates how to use Fragment and Views in Navigation3.

### Future recipes
The most upvoted [recipe requests]([url](https://github.com/android/nav3-recipes/issues?q=is%3Aissue%20state%3Aopen%20label%3Arecipe-request)) will be considered for implementation. Don't see your recipe? [File a request for one here](https://github.com/android/nav3-recipes/issues/new?template=1-recipe-request.md)

## Custom layout example
The following is a screen recording showing the navigation behavior of a [custom, list-detail Scene](app/src/main/java/com/example/nav3recipes/scenes/listdetail).

![Custom layout example](/docs/images/ListDetailScene.gif)

## Instructions
Clone this repository and open the root folder in [Android Studio](https://developer.android.com/studio). Each recipe is contained in its own package with its own `Activity`.

## Found an issue?
If the issue is _directly related to this project_, as in, it's reproducible without modifying this project's source code, then please [file an issue on github](https://github.com/android/nav3-recipes/issues/new?template=2-bug-report.md). If you've found an issue with the Jetpack Navigation 3 library, please [file an issue on the issue tracker](https://issuetracker.google.com/issues/new?component=1750212&template=2102223).

## Contributing
We'd love to accept your contributions. Please follow [these instructions](CONTRIBUTING.md).

## Compose Multiplatform Recipes
CMP recipes can be found [here](https://github.com/terrakok/nav3-recipes).

## License
```
Copyright 2025 The Android Open Source Project

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```