NavigationPath (SwiftUI)

Why it exists

SwiftUI's NavigationStack needs some ordered collection of what screen comes next to render as a stack. An Array of one concrete type works for simple flows, but real apps navigate through a mix of unrelated model types in one continuous stack, for example from a search result to a product to a specific review. NavigationPath exists to let that stack hold heterogeneous, arbitrarily typed values without forcing you into one shared enum or wrapper type for every possible destination up front.

The mental model

Think of NavigationPath as a coat check ticket stub stack rather than a labeled shelf. A labeled shelf, like a typed array, can only hold one kind of item. A stack of ticket stubs does not care what each ticket represents, it just remembers the order they were issued in and can hand back exactly what was checked in, in reverse order.

How it works

NavigationPath internally stores each pushed value in a type erased form, keeping just enough information, a hash and a way to recover the concrete type, to reconstruct it later. You append values with path.append, for example path.append(someBook), and pop with path.removeLast, or clear the whole stack at once. The NavigationStack view reads this path and, for each entry, looks for a matching navigationDestination for SomeType modifier in the view hierarchy to know which view to render for that entry's concrete type. Because NavigationPath conforms to Codable when every appended type is Codable, you can serialize the entire navigation stack to restore deep links or resume a saved session on next launch.

When it matters

It matters for any app with programmatic, deep, or state driven navigation: deep links that construct a multi screen path in one shot, push notifications that jump several levels deep, or restoring navigation state after backgrounding. The footgun is that popping to a specific screen means computing an index and truncating the path, there is no built in pop to type X helper, and mistakes cause either a crash from an out of range index or a stack that silently does not pop where expected.

A concrete example

A shopping app receives a push notification deep linking straight to a specific review screen. On launch it constructs a NavigationPath, appends the relevant Category, then the Product, then the Review, all in one line, and the NavigationStack renders the full three screen back stack immediately, so the user can tap back twice to reach the category browse screen exactly as if they had navigated there by hand.