androidx.navigation3.runtime

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

Provides a EntryProviderScope to build an entryProvider that provides NavEntries.

@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 rememberNavBackStack(vararg elements: NavKey): 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
fun rememberNavBackStack(
    configuration: SavedStateConfiguration,
    vararg elements: NavKey
): 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. It is designed specifically for open polymorphism of the NavKey type.

Serialization requirements

• All destination keys must be @Serializable and implement the NavKey interface.

• You must provide a SavedStateConfiguration containing a SerializersModule that registers all subtypes of NavKey. This is required to handle open polymorphism correctly across all platforms.

On Android, an overload of this function is available that does not require a SavedStateConfiguration. That version uses reflection internally and does not require subtypes to be registered, but it is not available on other platforms.

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(config, Home("start"))

@Composable
fun <T : Any> rememberSaveableStateHolderNavEntryDecorator(
    saveableStateHolder: SaveableStateHolder = rememberSaveableStateHolder()
): SaveableStateHolderNavEntryDecorator<T>

Returns a SaveableStateHolderNavEntryDecorator that is remembered across recompositions.