# NavDisplay

Common/AllAndroid/JVM

## Functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable <T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html> https://developer.android.com/reference/kotlin/androidx/navigation3/ui/NavDisplay.composable#NavDisplay(androidx.navigation3.scene.SceneState,androidx.navigationevent.compose.NavigationEventState,androidx.compose.ui.Modifier,androidx.compose.ui.Alignment,androidx.compose.animation.SizeTransform,kotlin.Function1,kotlin.Function1,kotlin.Function2)( sceneState: https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneState<T>, navigationEventState: https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventState<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneInfo<T>>, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, contentAlignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment, sizeTransform: https://developer.android.com/reference/kotlin/androidx/compose/animation/SizeTransform?, transitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.() -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform, popTransitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.() -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform, predictivePopTransitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.(https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform )` A nav display that renders and animates between different `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s, each of which can render one or more `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable <T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html> https://developer.android.com/reference/kotlin/androidx/navigation3/ui/NavDisplay.composable#NavDisplay(kotlin.collections.List,androidx.compose.ui.Modifier,androidx.compose.ui.Alignment,kotlin.collections.List,kotlin.collections.List,androidx.compose.animation.SharedTransitionScope,androidx.compose.animation.SizeTransform,kotlin.Function1,kotlin.Function1,kotlin.Function2,kotlin.Function0)( entries: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry<T>>, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, contentAlignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment, sceneStrategies: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneStrategy<T>>, sceneDecoratorStrategies: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneDecoratorStrategy<T>>, sharedTransitionScope: https://developer.android.com/reference/kotlin/androidx/compose/animation/SharedTransitionScope?, sizeTransform: https://developer.android.com/reference/kotlin/androidx/compose/animation/SizeTransform?, transitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.() -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform, popTransitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.() -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform, predictivePopTransitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.(https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform, onBack: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` A nav display that renders and animates between different `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s, each of which can render one or more `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable <T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html> https://developer.android.com/reference/kotlin/androidx/navigation3/ui/NavDisplay.composable#NavDisplay(kotlin.collections.List,androidx.compose.ui.Modifier,androidx.compose.ui.Alignment,kotlin.Function0,kotlin.collections.List,kotlin.collections.List,kotlin.collections.List,androidx.compose.animation.SharedTransitionScope,androidx.compose.animation.SizeTransform,kotlin.Function1,kotlin.Function1,kotlin.Function2,kotlin.Function1)( backStack: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<T>, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, contentAlignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment, onBack: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, entryDecorators: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntryDecorator<T>>, sceneStrategies: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneStrategy<T>>, sceneDecoratorStrategies: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneDecoratorStrategy<T>>, sharedTransitionScope: https://developer.android.com/reference/kotlin/androidx/compose/animation/SharedTransitionScope?, sizeTransform: https://developer.android.com/reference/kotlin/androidx/compose/animation/SizeTransform?, transitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.() -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform, popTransitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.() -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform, predictivePopTransitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.(https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform, entryProvider: (key) -> https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry<T> )` A nav display that renders and animates between different `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s, each of which can render one or more `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s. | Cmn |

## Functions

### NavDisplay

Cmn Artifact: [androidx.navigation3:navigation3-ui](https://developer.android.com/jetpack/androidx/releases/navigation3) [View Source](https://cs.android.com/search?q=file:androidx/navigation3/ui/NavDisplay.kt+function:NavDisplay)

```
@Composable
fun <T : Any> NavDisplay(
    sceneState: SceneState<T>,
    navigationEventState: NavigationEventState<SceneInfo<T>>,
    modifier: Modifier = Modifier,
    contentAlignment: Alignment = Alignment.TopStart,
    sizeTransform: SizeTransform? = null,
    transitionSpec: AnimatedContentTransitionScope<Scene<T>>.() -> ContentTransform = defaultTransitionSpec(),
    popTransitionSpec: AnimatedContentTransitionScope<Scene<T>>.() -> ContentTransform = defaultPopTransitionSpec(),
    predictivePopTransitionSpec: AnimatedContentTransitionScope<Scene<T>>.(Int) -> ContentTransform = defaultPredictivePopTransitionSpec()
): Unit
```

A nav display that renders and animates between different `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s, each of which can render one or more `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s.

By default, AnimatedContent transitions are prioritized in this order:

```kotlin
transitioning [NavEntry.metadata] > current [Scene.metadata] > NavDisplay defaults
```

However, a `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#metadata()` does have the ability to override `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry#metadata()`. Nevertheless, the final fallback will always be the NavDisplay's default transitions.

```kotlin
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.navigation3.runtime.NavEntry
import androidx.navigation3.runtime.rememberDecoratedNavEntries
import androidx.navigation3.scene.SceneInfo
import androidx.navigation3.scene.SinglePaneSceneStrategy
import androidx.navigation3.scene.rememberSceneState
import androidx.navigation3.ui.NavDisplay
import androidx.navigationevent.compose.NavigationBackHandler
import androidx.navigationevent.compose.rememberNavigationEventState

val backStack = rememberSaveable { mutableStateListOf("a", "b") }
val entries =
    rememberDecoratedNavEntries(backStack) { key -> NavEntry(key) { Text("Key = $key") } }
val sceneState =
    rememberSceneState(
        entries,
        listOf(SinglePaneSceneStrategy()),
        onBack = { backStack.removeLastOrNull() },
    )
val currentScene = sceneState.currentScene
val navigationEventState =
    rememberNavigationEventState(
        currentInfo = SceneInfo(currentScene),
        backInfo = sceneState.previousScenes.map { SceneInfo(it) },
    )
NavigationBackHandler(
    navigationEventState,
    isBackEnabled = currentScene.previousEntries.isNotEmpty(),
    onBackCompleted = {
        // Remove entries from the back stack until we've removed all popped entries
        repeat(entries.size - currentScene.previousEntries.size) {
            backStack.removeLastOrNull()
        }
    },
)
NavDisplay(sceneState, navigationEventState)
```

| Parameters |
|---|---|
| `sceneState: https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneState<T>` | the state that determines what current scene of the NavDisplay. |
| `navigationEventState: https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventState<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneInfo<T>>` | the `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventState` responsible for handling back navigation |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | the modifier to be applied to the layout. |
| `contentAlignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment = Alignment.TopStart` | The `https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment` of the `https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContent.composable#AnimatedContent(kotlin.Any,androidx.compose.ui.Modifier,kotlin.Function1,androidx.compose.ui.Alignment,kotlin.String,kotlin.Function1,kotlin.Function2)` |
| `sizeTransform: https://developer.android.com/reference/kotlin/androidx/compose/animation/SizeTransform? = null` | the `https://developer.android.com/reference/kotlin/androidx/compose/animation/SizeTransform` for the `https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContent.composable#AnimatedContent(kotlin.Any,androidx.compose.ui.Modifier,kotlin.Function1,androidx.compose.ui.Alignment,kotlin.String,kotlin.Function1,kotlin.Function2)`. |
| `transitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.() -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform = defaultTransitionSpec()` | Default `https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform` when navigating to `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s. |
| `popTransitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.() -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform = defaultPopTransitionSpec()` | Default `https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform` when popping `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s. |
| `predictivePopTransitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.(https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform = defaultPredictivePopTransitionSpec()` | Default `https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform` when popping with predictive back `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/rememberSceneState.composable#rememberSceneState(kotlin.collections.List,kotlin.collections.List,kotlin.collections.List,androidx.compose.animation.SharedTransitionScope,kotlin.Function0)` |   |

### NavDisplay

Cmn Artifact: [androidx.navigation3:navigation3-ui](https://developer.android.com/jetpack/androidx/releases/navigation3) [View Source](https://cs.android.com/search?q=file:androidx/navigation3/ui/NavDisplay.kt+function:NavDisplay)

```
@Composable
fun <T : Any> NavDisplay(
    entries: List<NavEntry<T>>,
    modifier: Modifier = Modifier,
    contentAlignment: Alignment = Alignment.TopStart,
    sceneStrategies: List<SceneStrategy<T>> = listOf(SinglePaneSceneStrategy()),
    sceneDecoratorStrategies: List<SceneDecoratorStrategy<T>> = emptyList(),
    sharedTransitionScope: SharedTransitionScope? = null,
    sizeTransform: SizeTransform? = null,
    transitionSpec: AnimatedContentTransitionScope<Scene<T>>.() -> ContentTransform = defaultTransitionSpec(),
    popTransitionSpec: AnimatedContentTransitionScope<Scene<T>>.() -> ContentTransform = defaultPopTransitionSpec(),
    predictivePopTransitionSpec: AnimatedContentTransitionScope<Scene<T>>.(Int) -> ContentTransform = defaultPredictivePopTransitionSpec(),
    onBack: () -> Unit
): Unit
```

A nav display that renders and animates between different `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s, each of which can render one or more `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s.

The `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s are calculated with the given list of `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneStrategy` in the order of the list. If no `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene` is calculated, the fallback will be to a `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SinglePaneSceneStrategy`.

It is allowable for different `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s to render the same `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s, perhaps on some conditions as determined by the `https://developer.android.com/reference/kotlin/androidx/navigation3/ui/package-summary#NavDisplay(kotlin.collections.List,androidx.compose.ui.Modifier,androidx.compose.ui.Alignment,kotlin.collections.List,kotlin.collections.List,androidx.compose.animation.SharedTransitionScope,androidx.compose.animation.SizeTransform,kotlin.Function1,kotlin.Function1,kotlin.Function2,kotlin.Function0)` based on window size, form factor, other arbitrary logic.

If this happens, and these `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s are rendered at the same time due to animation or predictive back, then the content for the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry` will only be rendered in the most recent `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene` that is the target for being the current scene as determined by `https://developer.android.com/reference/kotlin/androidx/navigation3/ui/package-summary#NavDisplay(kotlin.collections.List,androidx.compose.ui.Modifier,androidx.compose.ui.Alignment,kotlin.collections.List,kotlin.collections.List,androidx.compose.animation.SharedTransitionScope,androidx.compose.animation.SizeTransform,kotlin.Function1,kotlin.Function1,kotlin.Function2,kotlin.Function0)`. This enforces a unique invocation of each `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`, even if it is displayable by two different `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s.

By default, AnimatedContent transitions are prioritized in this order:

```kotlin
transitioning [NavEntry.metadata] > current [Scene.metadata] > NavDisplay defaults
```

However, a `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#metadata()` does have the ability to override `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry#metadata()`. Nevertheless, the final fallback will always be the NavDisplay's default transitions.

**WHEN TO USE** This overload can be used when you need to switch between different backStacks and each with their own separate decorator states, or when you want to concatenate backStacks and their states to form a larger backstack.

**HOW TO USE** The `https://developer.android.com/reference/kotlin/androidx/navigation3/ui/package-summary#NavDisplay(kotlin.collections.List,androidx.compose.ui.Modifier,androidx.compose.ui.Alignment,kotlin.collections.List,kotlin.collections.List,androidx.compose.animation.SharedTransitionScope,androidx.compose.animation.SizeTransform,kotlin.Function1,kotlin.Function1,kotlin.Function2,kotlin.Function0)` can first be created via `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/rememberDecoratedNavEntries.composable#rememberDecoratedNavEntries(kotlin.collections.List,kotlin.collections.List,kotlin.Function1)` in order to associate a backStack with a particular set of states.

```kotlin
import androidx.compose.material3.Icon
import androidx.compose.material3.NavigationBar
import androidx.compose.material3.NavigationBarItem
import androidx.compose.material3.Scaffold
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.navigation3.runtime.NavBackStack
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.ui.NavDisplay

val tabKeys = listOf(Home, User)

/** set up User entries */
val homeBackStack = rememberNavBackStack(Home)
val homeTabEntries =
    getHomeTabEntries(
        backStackString = homeBackStack.map { (it as SampleKey).name }.toString(),
        backStack = homeBackStack,
    )

/** set up User entries */
val userBackStack = rememberNavBackStack(User)
val userTabEntries =
    getUserTabEntries(
        backStackString = userBackStack.map { (it as SampleKey).name }.toString(),
        backStack = userBackStack,
    )

/** condition for which tab to switch to */
var currentTab: SampleTabKey by remember { mutableStateOf(Home) }

Scaffold(
    bottomBar = {
        NavigationBar {
            tabKeys.forEach { tab ->
                val isSelected = tab == currentTab
                NavigationBarItem(
                    selected = isSelected,
                    onClick = { currentTab = tab },
                    icon = { Icon(imageVector = tab.imageVector, contentDescription = null) },
                )
            }
        }
    }
) {
    /** Swap backStacks based on the current selected tab */
    NavDisplay(
        entries = if (currentTab == Home) homeTabEntries else userTabEntries,
        onBack = {
            val currBackStack = if (currentTab == Home) homeBackStack else userBackStack
            currBackStack.removeLastOrNull()
        },
    )
}
```

```kotlin
import androidx.compose.material3.Icon
import androidx.compose.material3.NavigationBar
import androidx.compose.material3.NavigationBarItem
import androidx.compose.material3.Scaffold
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.navigation3.runtime.NavBackStack
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.ui.NavDisplay

val tabKeys = listOf(Home, User)

/** set up User entries */
val homeBackStack = rememberNavBackStack(Home)
val homeBackStackNames = homeBackStack.map { (it as SampleKey).name }
val homeTabEntries =
    getHomeTabEntries(
        backStackString = homeBackStackNames.toString(),
        backStack = homeBackStack,
    )

/** set up User entries */
val userBackStack = rememberNavBackStack(User)
val userTabEntries =
    getUserTabEntries(
        backStackString =
            (homeBackStackNames + userBackStack.map { (it as SampleKey).name }).toString(),
        backStack = userBackStack,
    )

/** condition for which tab to switch to */
var currentTab: SampleTabKey by remember { mutableStateOf(Home) }

Scaffold(
    bottomBar = {
        NavigationBar {
            tabKeys.forEach { tab ->
                val isSelected = tab == currentTab
                NavigationBarItem(
                    selected = isSelected,
                    onClick = { currentTab = tab },
                    icon = { Icon(imageVector = tab.imageVector, contentDescription = null) },
                )
            }
        }
    }
) {
    /** Swap backStacks based on the current selected tab */
    NavDisplay(
        entries = if (currentTab == Home) homeTabEntries else homeTabEntries + userTabEntries,
        onBack = {
            val currBackStack = if (currentTab == Home) homeBackStack else userBackStack
            currBackStack.removeLastOrNull()
            if (currentTab == User && userBackStack.isEmpty()) {
                currentTab = Home
            }
        },
    )
}
```

```kotlin
import androidx.compose.animation.SharedTransitionLayout
import androidx.compose.runtime.remember
import androidx.navigation3.runtime.NavEntry
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.runtime.rememberSaveableStateHolderNavEntryDecorator
import androidx.navigation3.ui.NavDisplay

val backStack = rememberNavBackStack(CatList)
SharedTransitionLayout {
    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeAt(backStack.lastIndex) },
        entryDecorators = listOf(rememberSaveableStateHolderNavEntryDecorator()),
        sharedTransitionScope = this,
        entryProvider =
            entryProvider {
                entry<CatList> {
                    CatList(this@SharedTransitionLayout) { cat ->
                        backStack.add(CatDetail(cat))
                    }
                }
                entry<CatDetail> { args ->
                    CatDetail(args.cat, this@SharedTransitionLayout) {
                        backStack.removeAt(backStack.lastIndex)
                    }
                }
            },
    )
}
```

| Parameters |
|---|---|
| `entries: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry<T>>` | the list of `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry` built from a backStack. The entries can be created from a backStack decorated with `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntryDecorator` via `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/rememberDecoratedNavEntries.composable#rememberDecoratedNavEntries(kotlin.collections.List,kotlin.collections.List,kotlin.Function1)`. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | the modifier to be applied to the layout. |
| `contentAlignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment = Alignment.TopStart` | The `https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment` of the `https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContent.composable#AnimatedContent(kotlin.Any,androidx.compose.ui.Modifier,kotlin.Function1,androidx.compose.ui.Alignment,kotlin.String,kotlin.Function1,kotlin.Function2)` |
| `sceneStrategies: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneStrategy<T>> = listOf(SinglePaneSceneStrategy())` | the list of `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneStrategy` to determine which scene to render a list of entries. |
| `sceneDecoratorStrategies: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneDecoratorStrategy<T>> = emptyList()` | list of `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneDecoratorStrategy` to add content to the scene. |
| `sharedTransitionScope: https://developer.android.com/reference/kotlin/androidx/compose/animation/SharedTransitionScope? = null` | the `https://developer.android.com/reference/kotlin/androidx/compose/animation/SharedTransitionScope` to allow transitions between scenes. |
| `sizeTransform: https://developer.android.com/reference/kotlin/androidx/compose/animation/SizeTransform? = null` | the `https://developer.android.com/reference/kotlin/androidx/compose/animation/SizeTransform` for the `https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContent.composable#AnimatedContent(kotlin.Any,androidx.compose.ui.Modifier,kotlin.Function1,androidx.compose.ui.Alignment,kotlin.String,kotlin.Function1,kotlin.Function2)`. |
| `transitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.() -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform = defaultTransitionSpec()` | Default `https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform` when navigating to `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s. |
| `popTransitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.() -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform = defaultPopTransitionSpec()` | Default `https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform` when popping `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s. |
| `predictivePopTransitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.(https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform = defaultPredictivePopTransitionSpec()` | Default `https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform` when popping with predictive back `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s. |
| `onBack: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | a callback for handling system back press. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/rememberDecoratedNavEntries.composable#rememberDecoratedNavEntries(kotlin.collections.List,kotlin.collections.List,kotlin.Function1)` |   |

### NavDisplay

Cmn Artifact: [androidx.navigation3:navigation3-ui](https://developer.android.com/jetpack/androidx/releases/navigation3) [View Source](https://cs.android.com/search?q=file:androidx/navigation3/ui/NavDisplay.kt+function:NavDisplay)

```
@Composable
fun <T : Any> NavDisplay(
    backStack: List<T>,
    modifier: Modifier = Modifier,
    contentAlignment: Alignment = Alignment.TopStart,
    onBack: () -> Unit = {
        if (backStack is MutableList<T>) {
            backStack.removeLastOrNull()
        }
    },
    entryDecorators: List<NavEntryDecorator<T>> = listOf(rememberSaveableStateHolderNavEntryDecorator()),
    sceneStrategies: List<SceneStrategy<T>> = listOf(SinglePaneSceneStrategy()),
    sceneDecoratorStrategies: List<SceneDecoratorStrategy<T>> = emptyList(),
    sharedTransitionScope: SharedTransitionScope? = null,
    sizeTransform: SizeTransform? = null,
    transitionSpec: AnimatedContentTransitionScope<Scene<T>>.() -> ContentTransform = defaultTransitionSpec(),
    popTransitionSpec: AnimatedContentTransitionScope<Scene<T>>.() -> ContentTransform = defaultPopTransitionSpec(),
    predictivePopTransitionSpec: AnimatedContentTransitionScope<Scene<T>>.(Int) -> ContentTransform = defaultPredictivePopTransitionSpec(),
    entryProvider: (key) -> NavEntry<T>
): Unit
```

A nav display that renders and animates between different `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s, each of which can render one or more `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s.

The `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s are calculated with the given list of `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneStrategy` in the order of the list. If no `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene` is calculated, the fallback will be to a `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SinglePaneSceneStrategy`.

It is allowable for different `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s to render the same `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s, perhaps on some conditions as determined by the `https://developer.android.com/reference/kotlin/androidx/navigation3/ui/package-summary#NavDisplay(kotlin.collections.List,androidx.compose.ui.Modifier,androidx.compose.ui.Alignment,kotlin.Function0,kotlin.collections.List,kotlin.collections.List,kotlin.collections.List,androidx.compose.animation.SharedTransitionScope,androidx.compose.animation.SizeTransform,kotlin.Function1,kotlin.Function1,kotlin.Function2,kotlin.Function1)` based on window size, form factor, other arbitrary logic.

If this happens, and these `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s are rendered at the same time due to animation or predictive back, then the content for the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry` will only be rendered in the most recent `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene` that is the target for being the current scene as determined by `https://developer.android.com/reference/kotlin/androidx/navigation3/ui/package-summary#NavDisplay(kotlin.collections.List,androidx.compose.ui.Modifier,androidx.compose.ui.Alignment,kotlin.Function0,kotlin.collections.List,kotlin.collections.List,kotlin.collections.List,androidx.compose.animation.SharedTransitionScope,androidx.compose.animation.SizeTransform,kotlin.Function1,kotlin.Function1,kotlin.Function2,kotlin.Function1)`. This enforces a unique invocation of each `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`, even if it is displayable by two different `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`s.

By default, AnimatedContent transitions are prioritized in this order:

```kotlin
transitioning [NavEntry.metadata] > current [Scene.metadata] > NavDisplay defaults
```

However, a `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#metadata()` does have the ability to override `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry#metadata()`. Nevertheless, the final fallback will always be the NavDisplay's default transitions.

```kotlin
import androidx.compose.animation.core.tween
import androidx.compose.animation.slideInHorizontally
import androidx.compose.animation.slideOutHorizontally
import androidx.compose.animation.togetherWith
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.lifecycle.viewmodel.compose.viewModel
import androidx.lifecycle.viewmodel.navigation3.rememberViewModelStoreNavEntryDecorator
import androidx.navigation3.runtime.NavEntry
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.metadata
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.runtime.rememberSaveableStateHolderNavEntryDecorator
import androidx.navigation3.runtime.samples.Dashboard
import androidx.navigation3.runtime.samples.DialogBase
import androidx.navigation3.runtime.samples.DialogContent
import androidx.navigation3.runtime.samples.Profile
import androidx.navigation3.runtime.samples.ProfileViewModel
import androidx.navigation3.runtime.samples.Scrollable
import androidx.navigation3.ui.NavDisplay
import androidx.navigationevent.NavigationEvent

val backStack = rememberNavBackStack(Profile)
val showDialog = remember { mutableStateOf(false) }
NavDisplay(
    backStack = backStack,
    entryDecorators =
        listOf(
            rememberSaveableStateHolderNavEntryDecorator(),
            rememberViewModelStoreNavEntryDecorator(),
        ),
    onBack = { backStack.removeAt(backStack.lastIndex) },
    entryProvider =
        entryProvider({ NavEntry(it) { Text(text = "Invalid Key") } }) {
            entry<Profile> {
                val viewModel = viewModel<ProfileViewModel>()
                Profile(viewModel, { backStack.add(it) }) {
                    backStack.removeAt(backStack.lastIndex)
                }
            }
            entry<Scrollable> {
                Scrollable({ backStack.add(it) }) { backStack.removeAt(backStack.lastIndex) }
            }
            entry<DialogBase> {
                DialogBase(onClick = { showDialog.value = true }) {
                    backStack.removeAt(backStack.lastIndex)
                }
            }
            entry<Dashboard>(
                metadata =
                    metadata {
                        put(NavDisplay.PredictivePopTransitionKey) { swipeEdge: Int ->
                            if (swipeEdge == NavigationEvent.EDGE_RIGHT) {
                                slideInHorizontally(tween(700)) { it / 2 } togetherWith
                                    slideOutHorizontally(tween(700)) { -it / 2 }
                            } else {
                                slideInHorizontally(tween(700)) { -it / 2 } togetherWith
                                    slideOutHorizontally(tween(700)) { it / 2 }
                            }
                        }
                    }
            ) { dashboardArgs ->
                val userId = dashboardArgs.userId
                Dashboard(userId, onBack = { backStack.removeAt(backStack.lastIndex) })
            }
        },
)
if (showDialog.value) {
    DialogContent(onDismissRequest = { showDialog.value = false })
}
```

```kotlin
import androidx.compose.animation.SharedTransitionLayout
import androidx.compose.runtime.remember
import androidx.navigation3.runtime.NavEntry
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.runtime.rememberSaveableStateHolderNavEntryDecorator
import androidx.navigation3.ui.NavDisplay

val backStack = rememberNavBackStack(CatList)
SharedTransitionLayout {
    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeAt(backStack.lastIndex) },
        entryDecorators = listOf(rememberSaveableStateHolderNavEntryDecorator()),
        sharedTransitionScope = this,
        entryProvider =
            entryProvider {
                entry<CatList> {
                    CatList(this@SharedTransitionLayout) { cat ->
                        backStack.add(CatDetail(cat))
                    }
                }
                entry<CatDetail> { args ->
                    CatDetail(args.cat, this@SharedTransitionLayout) {
                        backStack.removeAt(backStack.lastIndex)
                    }
                }
            },
    )
}
```

```kotlin
import androidx.compose.animation.SharedTransitionLayout
import androidx.compose.runtime.remember
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.ui.NavDisplay

val backStack = rememberNavBackStack(CatList)
SharedTransitionLayout {
    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeAt(backStack.lastIndex) },
        entryProvider =
            entryProvider {
                entry<CatList> {
                    CatList(this@SharedTransitionLayout) { cat ->
                        backStack.add(CatDetail(cat))
                    }
                }
                entry<CatDetail> { args ->
                    CatDetail(args.cat, this@SharedTransitionLayout) {
                        backStack.removeAt(backStack.lastIndex)
                    }
                }
            },
    )
}
```

| Parameters |
|---|---|
| `backStack: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<T>` | the collection of keys that represents the state that needs to be handled |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | the modifier to be applied to the layout. |
| `contentAlignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment = Alignment.TopStart` | The `https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment` of the `https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContent.composable#AnimatedContent(kotlin.Any,androidx.compose.ui.Modifier,kotlin.Function1,androidx.compose.ui.Alignment,kotlin.String,kotlin.Function1,kotlin.Function2)` |
| `onBack: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = { if (backStack is MutableList<T>) { backStack.removeLastOrNull() } }` | a callback for handling system back press. By default, this pops a single item off of the given back stack if it is a `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-mutable-list/index.html`, otherwise you should provide this parameter. |
| `entryDecorators: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntryDecorator<T>> = listOf(rememberSaveableStateHolderNavEntryDecorator())` | list of `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntryDecorator` to add information to the entry content |
| `sceneStrategies: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneStrategy<T>> = listOf(SinglePaneSceneStrategy())` | the list of `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneStrategy` to determine which scene to render a list of entries. |
| `sceneDecoratorStrategies: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneDecoratorStrategy<T>> = emptyList()` | list of `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneDecoratorStrategy` to add content to the scene. |
| `sharedTransitionScope: https://developer.android.com/reference/kotlin/androidx/compose/animation/SharedTransitionScope? = null` | the `https://developer.android.com/reference/kotlin/androidx/compose/animation/SharedTransitionScope` to allow transitions between scenes. |
| `sizeTransform: https://developer.android.com/reference/kotlin/androidx/compose/animation/SizeTransform? = null` | the `https://developer.android.com/reference/kotlin/androidx/compose/animation/SizeTransform` for the `https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContent.composable#AnimatedContent(kotlin.Any,androidx.compose.ui.Modifier,kotlin.Function1,androidx.compose.ui.Alignment,kotlin.String,kotlin.Function1,kotlin.Function2)`. |
| `transitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.() -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform = defaultTransitionSpec()` | Default `https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform` when navigating to `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s. |
| `popTransitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.() -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform = defaultPopTransitionSpec()` | Default `https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform` when popping `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s. |
| `predictivePopTransitionSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentTransitionScope<https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene<T>>.(https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) -> https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform = defaultPredictivePopTransitionSpec()` | Default `https://developer.android.com/reference/kotlin/androidx/compose/animation/ContentTransform` when popping with predictive back `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s. |
| `entryProvider: (key) -> https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry<T>` | lambda used to construct each possible `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry` |