NavigationStack

What is NavigationStack

NavigationStack is SwiftUI's modern replacement for NavigationView, introduced in iOS 16. It provides a fully programmatic navigation experience with a type-safe API for pushing and popping views onto a navigation stack.

Unlike NavigationView, NavigationStack works with a NavigationPath — an observable collection that represents the navigation state. This makes it possible to save, restore, and manipulate the navigation stack from code.

Creating a NavigationStack

The simplest NavigationStack wraps content in a vertical navigation hierarchy:

import SwiftUI

struct ContentView: View {
    var body: some View {
        NavigationStack {
            List {
                NavigationLink("Go to Detail", value: "detail")
                NavigationLink("Go to Settings", value: "settings")
            }
            .navigationTitle("Home")
        }
    }
}

When a user taps a NavigationLink, SwiftUI pushes the corresponding view onto the stack. Tapping the back button pops it.

navigationDestination Modifier

The navigationDestination modifier is where you define which views correspond to which values. It uses a type-safe approach:

NavigationStack {
    List {
        NavigationLink("Go to Detail", value: DetailRoute.profile)
        NavigationLink("Go to Settings", value: DetailRoute.settings)
    }
    .navigationDestination(for: DetailRoute.self) { route in
        switch route {
        case .profile:
            ProfileView()
        case .settings:
            SettingsView()
        }
    }
}

You can stack multiple .navigationDestination modifiers for different types. SwiftUI resolves them based on the runtime type of the value.

Passing Data Through Navigation

NavigationLinks can carry associated data. For example:

NavigationLink("View Item", value: Item(id: 42, name: "Widget"))

.navigationDestination(for: Item.self) { item in
    ItemDetailView(item: item)
}

This pattern eliminates the need for @Binding or @ObservedObject gymnastics when passing data between screens.

Environment and Dismiss

Views inside a NavigationStack can use the @Environment(\.dismiss) property to pop themselves:

struct DetailView: View {
    @Environment(\.dismiss) var dismiss

    var body: some View {
        Button("Go Back") {
            dismiss()
        }
        .navigationTitle("Detail")
    }
}

This is the recommended way to programmatically pop a view from the stack.

NavigationStack vs NavigationSplitView

NavigationStack is for push/pop hierarchies (like on iPhone). NavigationSplitView is for column-based layouts (like on iPad). Choose based on your target interface. Many apps use both — NavigationSplitView at the top level on iPad, NavigationStack inside each column.

Understanding NavigationPath

NavigationPath is an observable collection that stores the navigation state of a NavigationStack. It holds a sequence of hashable values, each representing a view in the stack.

By binding a NavigationPath to your NavigationStack, you gain full programmatic control over navigation.

Binding a Path to NavigationStack

struct ContentView: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            List {
                NavigationLink("Go to Detail", value: 1)
                NavigationLink("Go to Profile", value: "profile")
            }
            .navigationDestination(for: Int.self) { id in
                DetailView(id: id)
            }
            .navigationDestination(for: String.self) { value in
                ProfileView(name: value)
            }
        }
    }
}

The path is a State variable. SwiftUI observes changes and updates the navigation accordingly.

Programmatic Push

You can push views onto the stack by appending values to the path:

struct ContentView: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            VStack {
                Button("Push Detail") {
                    path.append(42)
                }
                Button("Push Profile") {
                    path.append("Alice")
                }
            }
            .navigationDestination(for: Int.self) { id in
                DetailView(id: id)
            }
            .navigationDestination(for: String.self) { name in
                ProfileView(name: name)
            }
        }
    }
}

This is essential for flows like onboarding, where you want to advance to the next screen based on business logic.

Programmatic Pop

NavigationPath provides methods to remove views:

// Pop the last view
path.removeLast()

// Pop to root (remove all but the first view)
path.removeLast(path.count)

// Insert at a specific position
path.insert("settings", at: 0)

You can also remove a specific value if it exists in the path.

Codable NavigationPath

NavigationPath conforms to Codable, meaning you can save and restore navigation state:

struct AppState: Codable {
    var navigationPath: NavigationPath

    func encode(to encoder: Encoder) throws {
        var container = encoder.container(keyedBy: CodingKeys.self)
        try container.encode(navigationPath.codable, forKey: .navigationPath)
    }

    init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        let codable = try container.decode(NavigationPath.CodableRepresentation.self, forKey: .navigationPath)
        navigationPath = NavigationPath(codable)
    }
}

This pattern is powerful for deep linking, state restoration, and surviving app termination.

Count and Emptiness

NavigationPath exposes a count property. You can check emptiness to determine if the user is at the root:

if path.count > 0 {
    // User is not at root
} else {
    // User is at root
}

This is useful for showing different UI elements based on navigation depth.

Why Programmatic Navigation?

Sometimes you need to navigate based on business logic — not just user taps. For example:

• After a successful login, navigate to the main screen
• When a push notification arrives, open a specific detail view
• After completing a multi-step form, navigate to the confirmation screen

Programmatic navigation uses the NavigationPath to control the stack from code.

NavigationLink with Value

NavigationLink can trigger navigation by appending a value to the path:

NavigationLink("View Report", value: ReportRoute.dashboard)

Or using the trigger parameter for imperative navigation:

NavigationLink("Log In", value: AuthRoute.login, isActive: $shouldLogin)

Triggering Navigation from Async Operations

A common pattern is navigating after an async task completes:

struct LoginView: View {
    @State private var path = NavigationPath()
    @State private var isLoading = false

    var body: some View {
        NavigationStack(path: $path) {
            Button("Login") {
                isLoading = true
                Task {
                    try await authService.login()
                    isLoading = false
                    path.append(AppRoute.home)
                }
            }
            .navigationDestination(for: AppRoute.self) { route in
                switch route {
                case .home:
                    HomeView()
                case .profile:
                    ProfileView()
                }
            }
        }
    }
}

Replacing the Entire Stack

Sometimes you want to replace the entire navigation stack — for example, after logout:

// Clear the entire path and push a new root
path = NavigationPath()
path.append(AuthRoute.login)

Or pop to root and push a different view:

path.removeLast(path.count)
path.append(AppRoute.settings)

Navigation with Environment

The @Environment(\.navigationPath) property wrapper (available on iOS 17+) lets you access the navigation path from any child view without explicit binding:

struct ChildView: View {
    @Environment(\.navigationPath) private var navigationPath

    func openSettings() {
        navigationPath?.append(AppRoute.settings)
    }
}

Complex Navigation Flows

For multi-step flows, model each step as a route enum:

enum OnboardingStep: Hashable {
    case welcome
    case permissions
    case accountSetup
    case complete
}

Then manage the flow:

@State private var onboardingPath = NavigationPath()

func advanceToNextStep(current: OnboardingStep) {
    switch current {
    case .welcome: onboardingPath.append(.permissions)
    case .permissions: onboardingPath.append(.accountSetup)
    case .accountSetup: onboardingPath.append(.complete)
    case .complete: break
    }
}

This gives you full control over multi-screen flows without manual view management.