NavigationPath and Programmatic Navigation
NavigationStack can be driven purely by user taps on NavigationLinks, but many real apps need to push, pop, or reset navigation state from code — after a successful login, after finishing a multi-step form, or when handling a deep link from a push notification. NavigationPath is the type-erased collection of Hashable values representing the current stack, and by binding a NavigationStack's path to a @State (or @Observable) NavigationPath, you gain full programmatic control: append to push, mutate to pop, or replace the whole path to jump straight to a specific screen.
Cricket analogy: Just as a match can be driven by the umpire's manual signals ball by ball, a captain reviewing a DRS decision programmatically overturns the on-field call; NavigationPath similarly lets code append or reset the stack, not just user taps.
Binding a Stack to a Path
NavigationStack(path:) takes a Binding<NavigationPath> (or a binding to an array of a single Hashable type, if you don't need heterogeneous values). Once bound, appending a value to the path is equivalent to the user tapping a NavigationLink(value:) for that value, and removing values from the path pops those screens. This means a 'submit' button handler, a network callback, or a deep-link router can all drive navigation the exact same way a manual tap would.
Cricket analogy: Just as a scorer manually recording a boundary is equivalent to the umpire's official signal, appending a value to NavigationPath is equivalent to a user tapping NavigationLink(value:) — both drive the exact same stack transition.
@Observable
final class AppRouter {
var path = NavigationPath()
func showRecipe(_ recipe: Recipe) {
path.append(recipe)
}
func popToRoot() {
path.removeLast(path.count)
}
}
struct RootView: View {
@State private var router = AppRouter()
var body: some View {
NavigationStack(path: $router.path) {
RecipeListView(onSelect: router.showRecipe)
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetailView(recipe: recipe)
}
}
.environment(router)
}
}Popping and Resetting
Because NavigationPath behaves like a collection, popping the top screen is as simple as removeLast(), and popping to root is removeLast(path.count) or, more simply, reassigning path = NavigationPath(). This is the standard way to implement 'after checkout succeeds, return to the home screen' flows without needing a chain of dismiss() calls across multiple views.
Cricket analogy: Popping back to the home screen after a match ends by reassigning path = NavigationPath() is like resetting the scoreboard to the tournament home page instead of manually clicking 'back' through every over's replay screen.
Deep Linking
To support deep links (from a URL, push notification, or Shortcuts action), a router object typically parses the incoming link into one or more Hashable values and appends them to the path in order, reconstructing the exact stack a user would have built by tapping through manually. Since navigationDestination(for:) already knows how to render each type, the destination views themselves don't need any special deep-linking awareness.
Cricket analogy: A push notification about a wicket falling parses into a Hashable match-ID and over-number, appended to the path in order, reconstructing exactly the screens a fan would have tapped through to reach that ball live.
NavigationPath is type-erased, which means it can hold a heterogeneous mix of Hashable types, but this also means you cannot inspect its contents by index the way you would a typed array — you generally only append, remove, or replace it wholesale. For simpler apps with a single pushed type, a plain Binding<[MyType]> is often more ergonomic than NavigationPath.
A useful analogy: NavigationPath is like a GPS route rather than a single turn-by-turn instruction — you can hand it an entire sequence of destinations at once (e.g. from a deep link) and the NavigationStack will materialize every intermediate screen needed to arrive there, not just the final one.
- NavigationPath is a type-erased, Hashable-backed representation of a NavigationStack's current push history.
- Binding NavigationStack(path:) to a NavigationPath enables pushing, popping, and resetting navigation entirely from code.
- Appending a value to the path is equivalent to a user tapping a matching NavigationLink(value:).
- path.removeLast(path.count), or reassigning a fresh NavigationPath(), pops back to the root screen.
- Deep linking works by parsing an incoming link into one or more Hashable values and appending them to reconstruct the stack.
- For a single pushed type, a plain Binding<[MyType]> can be simpler than the type-erased NavigationPath.
Practice what you learned
1. What must a NavigationStack be bound to in order to support fully programmatic navigation?
2. What is the effect of appending a Recipe value to a bound NavigationPath, assuming a matching navigationDestination(for: Recipe.self) exists?
3. What is the correct way to programmatically pop an entire NavigationStack back to its root screen?
4. Why is NavigationPath described as 'type-erased'?
5. What is a typical strategy for handling a deep link (e.g. from a push notification) with NavigationPath?
Was this page helpful?
You May Also Like
NavigationStack Basics
Understand how NavigationStack replaced NavigationView, how navigationDestination drives push navigation, and how to structure hierarchical screens in SwiftUI.
The @Observable Macro
See how the iOS 17 @Observable macro replaces ObservableObject with automatic, fine-grained property tracking that simplifies SwiftUI model code.
Passing Data Between Views
A practical guide to the different ways data flows through a SwiftUI view hierarchy — initializers, @Binding, environment, and shared observable models.
TabView and Sheets
Compare SwiftUI's two main top-level presentation patterns — persistent tab-based navigation with TabView and modal, dismissible content with sheets.