resetRoot

Clear the existing backstack of screens and navigate to newRoot.

This is useful in preventing the user from returning to a completed workflow, such as a tutorial, wizard, or authentication flow.

Example

val navigator = Navigator()
navigator.push(LoginScreen1)
navigator.push(LoginScreen2)

// Login flow is complete. Wipe backstack and set new root screen
val loginScreens = navigator.resetRoot(HomeScreen)

Multiple back stacks

The StateOptions parameter enable functionality what is commonly called 'multiple back stacks'. By optionally saving, and later restoring the back stack, you can enable different root screens to have their own back stacks. A common use case is with the bottom navigation bar UX pattern.

val options = StateOptions.SaveAndRestore
navigator.resetRoot(HomeNavTab1, options)
// User navigates to a details screen
navigator.push(EntityDetails(id = foo))
// Later, user clicks on a bottom navigation item
navigator.resetRoot(HomeNavTab2, options)
// Later, user switches back to the first navigation item
navigator.resetRoot(HomeNavTab1, options)
// The existing back stack is restored, and EntityDetails(id = foo) will be top of
// the back stack

There are times when saving and restoring the back stack may not be appropriate, so use this feature only when it makes sense. A common example where it probably does not make sense is launching screens which define a UX flow which has a defined completion, such as onboarding.

Parameters