androidx.navigation3.runtime

fun <T : Any> SavedStateNavEntryDecorator(
    saveableStateHolder: SaveableStateHolder
): NavEntryDecorator<T>

Wraps the content of a NavEntry with a SaveableStateHolder.SaveableStateProvider to ensure that calls to rememberSaveable within the content work properly and that state can be saved. Also provides the content of a NavEntry with a SavedStateRegistryOwner which can be accessed in the content with LocalSavedStateRegistryOwner.

This NavEntryDecorator is the only one that is required as saving state is considered a non-optional feature.

inline fun <T : Any> entryProvider(
    noinline fallback: (unknownScreen) -> NavEntry<T> = {
        throw IllegalStateException("Unknown screen $it")
    },
    builder: EntryProviderBuilder<T>.() -> Unit
): (T) -> NavEntry<T>

Creates an EntryProviderBuilder with the entry providers provided in the builder.

fun <T : Any> navEntryDecorator(
    onPop: (contentKey: Any) -> Unit = {},
    decorator: @Composable (entry: NavEntry<T>) -> Unit
): NavEntryDecorator<T>

Function to decorate the NavEntry that are integrated with a rememberDecoratedNavEntries.

Primary usages include but are not limited to:

1. provide information to entries with androidx.compose.runtime.CompositionLocal, i.e.

val decorator = navEntryDecorator<Any> { entry ->
   ...
   CompositionLocalProvider(LocalMyStateProvider provides myState) {
       entry.content.invoke(entry.key)
   }
}

1. Wrap entry content with other composable content

val decorator = navEntryDecorator<Any> { entry ->
   ...
   MyComposableFunction {
       entry.content.invoke(entry.key)
   }
}

@Composable
fun <T : Any> rememberDecoratedNavEntries(
    entries: List<NavEntry<T>>,
    entryDecorators: List<NavEntryDecorator<T>> = listOf()
): List<NavEntry<T>>

Decorates the entries with the entryDecorators and returns the list of decorated NavEntries.

WHEN TO USE This API can be used to decorate undecorated NavEntry as well as entries that have already been decorated with other NavEntryDecorator.

HOW IT WORKS When you redecorate NavEntries with this function, the entryDecorators passed in here will be invoked first, followed by the original decorators that decorated the entries. For example

val originalDecorator = listOf(navEntryDecorator { println("original") })
val originalEntries = rememberDecoratedNavEntries(backStack, originalDecorator, ...)

val newDecorator = listOf(navEntryDecorator { println("additional") })
val newEntries = rememberDecoratedNavEntries(originalEntries, newDecorator)

// println output
additional
original

@Composable
fun <T : Any> rememberDecoratedNavEntries(
    backStack: List<T>,
    entryDecorators: List<NavEntryDecorator<T>> = listOf(),
    entryProvider: (key) -> NavEntry<T>
): List<NavEntry<T>>

Remembers and returns a list of NavEntry decorated with the list of entryDecorators

The returned list of NavEntry survives configuration change and recompositions but does not survive process death. To ensure that the backStack and its states are recovered properly, the backStack and the entryDecorators's states passed into this function should be hoisted and saved across process death.

For example:

// backStack saved during process death
val backStack = rememberNavBackStack()

// the hoisted SaveableStateHolder used by the decorator is saved during process death
val decorators = listOf(rememberSavedStateNavEntryDecorator())

// finally, decorate the entries
val entries = rememberDecoratedNavEntries(backStack, decorators, entryProvider)

HOW TO USE The returned list of entries should be stored and reused for the same backStack. If you want to support multiple backStacks (i.e. each bottom tab with their own backStack), then each backStack should be their own rememberDecoratedNavEntries with new backStack and entryDecorators passed in.

MUTABLE BACKSTACK NAVIGATE/POP The backStack should be a hoisted OBSERVABLE list, and navigates or pops should be applied directly to this backStack. For example:

val backStack = mutableStateListOf(A)
val entries = rememberDecoratedNavEntries(backStack, ...)

// to navigate
backStack.add(B)

// to pop
backStack.removeLastOrNull()

IMMUTABLE BACKSTACK NAVIGATE/POP This composable also supports navigates and pops with immutable backStack. Simply replace the previous backStack with a new one but DO NOT replace the decorator states. Also, DO NOT create a brand new rememberDecoratedNavEntries. For example

val backStack = mutableStateOf(listOf(1, 2))
val entries = rememberDecoratedNavEntries(backStack, ...)

// to navigate
backStack.value = listOf(1, 2, 3)

// to pop
backStack.value = listOf(1)

MULTIPLE BACKSTACKS Each call to rememberDecoratedNavEntries represents a single backStack. To support multiple backStack, there should be one rememberDecoratedNavEntries for each backStack. For example

val homeBackStack = mutableStateListOf(HomeKey)
val homeDecorators = mutableStateListOf(rememberSavedStateNavEntryDecorator(), ...)
val homeTabEntries = rememberDecoratedNavEntries(homeBackStack, homeDecorators, ...)

val favoritesBackStack = mutableStateListOf(FavoritesKey)
val favoritesDecorators = mutableStateListOf(rememberSavedStateNavEntryDecorator(),...)
val favoritesTabEntries = rememberDecoratedNavEntries(favoritesBackStack, favoritesDecorators, ...)

You can also concatenate multiple backStacks to form a larger one. So, given the above setup:

val concatenatedEntries = homeTabEntries + favoritesTabEntries

// To navigate within the favorites backStack
favoritesBackStack.add(FavoritesDetailKey)

In this case, the updated favoritesBackStack and updated states will be reflected in concatenatedEntries.

@Composable
fun <T : NavKey> rememberNavBackStack(vararg elements: T): NavBackStack<NavKey>

Provides a NavBackStack that is automatically remembered in the Compose hierarchy across process death and configuration changes.

This overload does not take a SavedStateConfiguration. It relies on the platform default: on Android, state is saved/restored using a reflection-based serializer; on other platforms this will fail at runtime. If you target non-Android platforms, use the overload that accepts a SavedStateConfiguration and register your serializers explicitly.

When to use this overload

• You are on Android only and want a simple API that uses reflection under the hood.

• Your back stack elements use closed polymorphism (sealed hierarchies) or otherwise work with Android’s reflective serializer.

Serialization requirements

• Each element placed in the NavBackStack must be @Serializable.

• For closed polymorphism (sealed hierarchies), the compiler knows all subtypes and generates serializers; Android’s reflection will also work.

• For open polymorphism (interfaces or non-sealed hierarchies):

• On Android, the reflection path can handle subtypes without manual registration.

• On non-Android, this overload is unsupported; use the configuration overload and register all subtypes of NavKey in a SerializersModule.

import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.runtime.samples.RememberNavBackStackSamples.Details
import androidx.navigation3.runtime.samples.RememberNavBackStackSamples.Home

// Works on Android (uses reflection internally).
rememberNavBackStack(Home("start"), Details(42))

@Composable
inline fun <T : NavKey> rememberNavBackStack(
    configuration: SavedStateConfiguration,
    vararg elements: T
): NavBackStack<NavKey>

Provides a NavBackStack that is automatically remembered in the Compose hierarchy across process death and configuration changes.

This function uses NavBackStackSerializer under the hood to save and restore the back stack via rememberSerializable.

Serialization requirements

• Each element placed in the NavBackStack must be @Serializable.

• For closed polymorphism (sealed hierarchies), the compiler knows all subtypes and generates serializers automatically. No custom SavedStateConfiguration is required.

• For open polymorphism (interfaces or non-sealed hierarchies):

• On Android, SavedStateConfiguration.DEFAULT uses a reflective serializer that can handle subtypes without registration.

• On other platforms, or when you supply a custom configuration, you must register all subtypes of NavKey in a SerializersModule and pass that via configuration. You must also provide the same configuration to the encoder/decoder when saving/restoring state.

import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.runtime.samples.RememberNavBackStackSamples.Details
import androidx.navigation3.runtime.samples.RememberNavBackStackSamples.Home
import androidx.navigation3.runtime.samples.RememberNavBackStackSamples.Screen
import androidx.savedstate.serialization.SavedStateConfiguration

val config = SavedStateConfiguration {
    // Register subtypes for open polymorphism or multiplatform use.
    serializersModule = SerializersModule {
        polymorphic(baseClass = Screen::class) {
            subclass(serializer = Home.serializer())
            subclass(serializer = Details.serializer())
        }
    }
}

// Pass the configuration so encoding/decoding works consistently.
rememberNavBackStack<Screen>(config, Home("start"))

@Composable
fun <T : Any> rememberSavedStateNavEntryDecorator(
    saveableStateHolder: SaveableStateHolder = rememberSaveableStateHolder()
): NavEntryDecorator<T>

Returns a SavedStateNavEntryDecorator that is remembered across recompositions.