# Scene

Artifact: [androidx.navigation3:navigation3-ui](https://developer.android.com/jetpack/androidx/releases/navigation3) [View Source](https://cs.android.com/search?q=file:androidx/navigation3/scene/Scene.kt+class:androidx.navigation3.scene.Scene) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigation3#1.0.0) Common/All
- Cmn

  ```
  interface Scene<T : Any>
  ```
Known direct subclasses [OverlayScene](https://developer.android.com/reference/kotlin/androidx/navigation3/scene/OverlayScene)

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/OverlayScene` | A specific scene to render 1 or more `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry` instances as an overlay. |

*** ** * ** ***

A specific scene to render 1 or more `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s.

A scene instance is identified by its `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#key()` and the class of the `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`, and this change drives the top-level animation based on the `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneStrategy` calculating what the current `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene` is for the backstack.

The rendering for `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#content()` should invoke the content for each `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry` contained in `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#entries()` at most once concurrently in a given `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`.

It is valid for two different instances of a `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene` to render the same `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`. In this situation, the content for a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry` will only be rendered in the most recent target `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene` that it is displayed in, as determined by `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#entries()`.

**Important** Implementations of this interface should either be data classes, or implement equals and hashcode to ensure that the same `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene` is used when appropriate.

## Summary

| ### Public properties |
|---|---|---|
| `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#content()` The content rendering the `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene` itself. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry<T>>` | `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#entries()` The list of `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s that can be displayed in this scene. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#key()` The key identifying the `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html>` | `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#metadata()` Provide `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`-specific information to `https://developer.android.com/reference/kotlin/androidx/navigation3/ui/NavDisplay`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry<T>>` | `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#previousEntries()` The resulting `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s that should be computed after pressing back updates the backstack. | Cmn |

## Public properties

### content

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigation3#1.0.0)

```
val content: @Composable () -> Unit
```

The content rendering the `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene` itself.

This should call the content for the `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#entries()`, and can add any arbitrary UI around them specific to the `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`.

### entries

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigation3#1.0.0)

```
val entries: List<NavEntry<T>>
```

The list of `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s that can be displayed in this scene.

When animating between scenes, the underlying content for each `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry` will only be rendered by the scene that is most recently the target scene, and is displaying that `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry` as determined by this `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#entries()` list.

For example, consider a transition from `Scene1` to `Scene2` below:

```kotlin
Scene1:      Scene2:
+---+---+     +---+---+
|   |   |     |   |   |
| A | B | --> | B | C |
|   |   |     |   |   |
+---+---+     +---+---+
```

`Scene1.entries` should be `[A, B]`, and `Scene2.entries` should be `[B, C]`

When both are being rendered at the same time during the transition, the content for `A` will be rendered in `Scene1`, while the content for `B` and `C` will be rendered in `Scene2`.

### key

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigation3#1.0.0)

```
val key: Any
```

The key identifying the `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`. This key will be combined with the class of the `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene` to determine the key that drives the transition in the top-level animation for the NavDisplay.

Because the class of the `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene` is also used, this `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#key()` only needs to be unique for a given type of `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene` to indicate a different instance of the `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`.

### metadata

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigation3#1.0.0)

```
open val metadata: Map<String, Any>
```

Provide `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene`-specific information to `https://developer.android.com/reference/kotlin/androidx/navigation3/ui/NavDisplay`.

By default includes the metadata of the last `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry` in `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/Scene#entries()`.

```kotlin
import androidx.compose.foundation.layout.Box
import androidx.navigation3.runtime.NavEntry
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.runtime.rememberSaveableStateHolderNavEntryDecorator
import androidx.navigation3.scene.Scene
import androidx.navigation3.scene.SceneStrategy
import androidx.navigation3.ui.NavDisplay

val backStack = rememberNavBackStack(A)
NavDisplay(
    backStack,
    onBack = { backStack.removeLastOrNull() },
    entryDecorators = listOf(rememberSaveableStateHolderNavEntryDecorator()),
    // NavDisplay default transitions slide vertically
    transitionSpec = { slideVertical },
    popTransitionSpec = { slideVertical },
    predictivePopTransitionSpec = { slideVertical },
    // but the Scene provides default transitions that slide horizontally
    sceneStrategies = listOf(DefaultSceneTransitionsSceneStrategy()),
    entryProvider =
        entryProvider {
            entry<A> { BlueBox("A") { backStack.add(B) } }
            entry<B> { RedBox("B") }
        },
)
```

```kotlin
import androidx.compose.foundation.layout.Box
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.scene.Scene
import androidx.navigation3.scene.SceneStrategy
import androidx.navigation3.ui.NavDisplay

val backStack = rememberNavBackStack(A)
NavDisplay(
    backStack,
    onBack = { backStack.removeLastOrNull() },
    entryDecorators = listOf(rememberSaveableStateHolderNavEntryDecorator()),
    // the Scene overrides the NavEntry's slide vertical with slide horizontal transitions
    sceneStrategies = listOf(SceneOverrideEntryTransitionsSceneStrategy()),
    entryProvider =
        entryProvider {
            entry<A> { BlueBox("A") { backStack.add(B) } }
            // the entry defines slide vertical transitions
            entry<B>(
                metadata =
                    metadata {
                        put(NavDisplay.TransitionKey) { slideVertical }
                        put(NavDisplay.PopTransitionKey) { slideVertical }
                        put(NavDisplay.PredictivePopTransitionKey, { _: Int -> slideVertical })
                    }
            ) {
                RedBox("B")
            }
        },
)
```

### previousEntries

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigation3#1.0.0)

```
val previousEntries: List<NavEntry<T>>
```

The resulting `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/NavEntry`s that should be computed after pressing back updates the backstack.

This is required for calculating the proper predictive back state, which may result in a different scene being shown.

When predictive back is occurring, this list of entries will be passed through the `https://developer.android.com/reference/kotlin/androidx/navigation3/scene/SceneStrategy` again, to determine what the resulting scene would be if the back happens.