OverlayScene

Artifact: androidx.navigation3:navigation3-ui

Added in 1.0.0

Cmn

interface OverlayScene<T : Any> : Scene

A specific scene to render 1 or more NavEntry instances as an overlay.

It is expected that the content is rendered in one or more separate windows (e.g., a dialog, popup window, etc.) that are visible above any additional Scene instances calculated from the overlaidEntries.

When processing overlaidEntries, expect processing of each SceneStrategy to restart from the first strategy. This may result in multiple instances of the same OverlayScene to be shown simultaneously, making a unique key even more important.

Important Implementations of this interface should either be data classes, or implement equals and hashcode to ensure that the same Scene is used when appropriate.

Summary

Public functions
`open suspend Unit`	`onRemove()` Callback that is invoked after this `OverlayScene` is popped from the backStack, but before it leaves composition.	Cmn

Public properties
`List<NavEntry<T>>`	`overlaidEntries` The `NavEntry`s that should be handled by another `Scene` that sits below this Scene.	Cmn

Inherited properties

From androidx.navigation3.scene.Scene

`@Composable () -> Unit`	`content` The content rendering the `Scene` itself.	Cmn
`List<NavEntry<T>>`	`entries` The list of `androidx.navigation3.runtime.NavEntry`s that can be displayed in this scene.	Cmn
`Any`	`key` The key identifying the `Scene`.	Cmn
`open Map<String, Any>`	`metadata` Provide `Scene`-specific information to `androidx.navigation3.ui.NavDisplay`.	Cmn
`List<NavEntry<T>>`	`previousEntries` The resulting `NavEntry`s that should be computed after pressing back updates the backstack.	Cmn

Public functions

onRemove

Cmn

Added in 1.1.0

open suspend fun onRemove(): Unit

Callback that is invoked after this OverlayScene is popped from the backStack, but before it leaves composition.

Animations for exiting overlays should be implemented within onRemove. This ensures that any suspending animations or other suspending work completes before the overlay is removed from composition.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.metadata
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.scene.Scene
import androidx.navigation3.scene.SceneStrategy
import androidx.navigation3.ui.NavDisplay

val backStack = rememberNavBackStack(Landing)
NavDisplay(
    backStack = backStack,
    onBack = { backStack.removeLastOrNull() },
    sceneStrategies = listOf(AnimatedBottomSheetSceneStrategy()),
    entryProvider =
        entryProvider {
            entry<Landing> {
                Box(Modifier.fillMaxSize().background(Color.Green)) {
                    Button(onClick = { backStack.add(AnimatedBottomSheet) }) {
                        Text("Click to open bottom sheet")
                    }
                }
            }
            entry<AnimatedBottomSheet>(
                metadata = AnimatedBottomSheetSceneStrategy.bottomSheet()
            ) {
                Column {
                    Text("BottomSheet")
                    Button(onClick = { backStack.removeLastOrNull() }) {
                        Text("Close BottomSheet")
                    }
                }
            }
        },
)

Public properties

overlaidEntries

Cmn

Added in 1.0.0

val overlaidEntries: List<NavEntry<T>>

The NavEntrys that should be handled by another Scene that sits below this Scene.

This must always be a non-empty list to correctly display entries below the overlay.

In general the default value for this should be the same as previousEntries.