SwiftUI NavigationStack: Type-Safe, Programmatic Navigation

Why NavigationStack replaced NavigationView

NavigationView is deprecated because its navigation state was implicit and hard to control — you nested NavigationLinks and toggled isActive booleans that quickly became unmanageable. NavigationStack flips the model: you navigate by presenting values, and a single stack owns the history. This makes state restoration, deep linking, and unit-testable routing straightforward. If you are still on NavigationView, migrating is usually mechanical, and it unlocks the entire value-based API described below.

// Deprecated
NavigationView {
    List(items) { item in
        NavigationLink(destination: DetailView(item: item)) {
            Text(item.name)
        }
    }
}

// Modern
NavigationStack {
    List(items) { item in
        NavigationLink(value: item) { Text(item.name) }
    }
    .navigationDestination(for: Item.self) { item in
        DetailView(item: item)
    }
}

Value-based destinations

The core idea is separation: a NavigationLink(value:) only says which value should be pushed, while navigationDestination(for:) declares how to render each type of value. Any Hashable value works, so you can register multiple destination types on the same stack — one for Item, another for a settings route enum. Because links carry data rather than views, you can generate them in a ForEach without eagerly constructing every destination, which keeps large lists efficient.

NavigationStack {
    List {
        ForEach(products) { product in
            NavigationLink(value: product) { Text(product.title) }
        }
        NavigationLink("Settings", value: Route.settings)
    }
    .navigationDestination(for: Product.self) { ProductDetail(product: $0) }
    .navigationDestination(for: Route.self) { route in
        switch route {
        case .settings: SettingsView()
        }
    }
}

Programmatic control with NavigationPath

For full programmatic navigation, bind a path with NavigationStack(path:). NavigationPath is a type-erased collection that can hold values of different Hashable types at once. Append to push a screen, call removeLast() to pop, and set it to an empty NavigationPath() to pop all the way to the root. Store this path in an observable Router object so any part of your app — a notification handler, a widget tap — can drive navigation without passing bindings everywhere.

@Observable
final class Router {
    var path = NavigationPath()
    func push(_ value: any Hashable) { path.append(value) }
    func popToRoot() { path = NavigationPath() }
}

struct RootView: View {
    @State private var router = Router()
    var body: some View {
        NavigationStack(path: $router.path) {
            HomeView()
                .navigationDestination(for: Product.self) { ProductDetail(product: $0) }
        }
        .environment(router)
    }
}

Deep-link restoration

Because the entire back stack is expressed as a path of values, restoring a deep link is just building the right array. Parse an incoming URL into your route values and assign them to the path in order; SwiftUI pushes the whole stack so the user lands on the deep screen with a working back button. For persistence across launches, make your route enum Codable and encode the path with NavigationPath's CodableRepresentation. This is the feature NavigationView never had.

func handle(_ url: URL) {
    // myapp://product/42/reviews
    guard url.host == "product",
          let id = Int(url.pathComponents[safe: 1] ?? "") else { return }
    router.path = NavigationPath()
    router.path.append(Product(id: id))
    if url.pathComponents.last == "reviews" {
        router.path.append(Route.reviews(productID: id))
    }
}

Toolbars and titles

Inside a NavigationStack, attach .navigationTitle to name a screen and .toolbar to add bar buttons. Use ToolbarItem with a placement such as .topBarTrailing or .topBarLeading for precise positioning, and .navigationBarTitleDisplayMode to switch between large and inline titles. On iOS 26, the navigation bar adopts the Liquid Glass material and toolbar items can be grouped with ToolbarItemGroup so they share a glass background as the user scrolls.

DetailView()
    .navigationTitle("Order Details")
    .navigationBarTitleDisplayMode(.inline)
    .toolbar {
        ToolbarItem(placement: .topBarTrailing) {
            Button("Edit") { isEditing = true }
        }
        ToolbarItem(placement: .topBarLeading) {
            Button("Close", role: .cancel) { dismiss() }
        }
    }

How to migrate from NavigationView to NavigationStack

Move an existing screen to the modern value-based navigation model in four steps.

1. 1

   Swap the container

   Replace NavigationView with NavigationStack. Split-view layouts should move to NavigationSplitView instead.

   NavigationStack { /* content */ }

2. 2

   Convert links to values

   Change NavigationLink(destination:) to NavigationLink(value:) carrying a Hashable value.

   NavigationLink(value: item) { Text(item.name) }

3. 3

   Register destinations

   Add navigationDestination(for:) once per value type to map values to views.

   .navigationDestination(for: Item.self) { DetailView(item: $0) }

4. 4

   Add a path for control

   If you need programmatic navigation, bind NavigationStack(path:) to a NavigationPath.

   NavigationStack(path: $router.path) { ... }

Frequently Asked Questions