NavigationStack: What Is It, Navigation Stack in SwiftUI

What is NavigationStack in SwiftUI?

NavigationStack is a container View implementing stack-based navigation (LIFO). It manages the transition history, allowing you to push new screens onto the stack and go back via the system “Back” button or programmatically. NavigationStack is part of SwiftUI starting from iOS 16, iPadOS 16, macOS 13, watchOS 9, and tvOS 16.

The main innovation of NavigationStack is the type-safe navigation path. Instead of directly specifying a destination when creating a NavigationLink, you put a value into the path, and the destination View is registered separately via the .navigationDestination(for:destination:) modifier. This separates navigation from rendering, making the code more modular and testable.

According to WWDC 2022 (Session 10054), NavigationStack uses a new navigation mechanism based on ObservableObject and the SwiftUI lifecycle. Unlike NavigationView, which relied on UINavigationController under the hood, NavigationStack is fully implemented in SwiftUI, improving predictability and compatibility with the SwiftUI lifecycle.

Basic Structure of NavigationStack

NavigationStack accepts a root View and an optional navigation path (Binding to NavigationPath or an array of Hashable values). All child screens are pushed onto the stack via NavigationLink or by programmatically adding values to the path.

NavigationStack vs NavigationView: Comparison

NavigationView was the main navigation container in SwiftUI before iOS 16. It automatically managed UINavigationController under the hood, which led to several issues: unpredictable behavior when data changed, complexity with programmatic navigation, and lack of type safety.

Key advantage of NavigationStack — type-safe navigation. You define the path as an array of specific types (or NavigationPath for heterogeneous stacks) and register a destination for each type. This eliminates type mismatch errors and makes navigation predictable.

NavigationView is deprecated in iOS 17. Apple recommends migrating to NavigationStack for all new projects and when updating the minimum version to iOS 16.

NavigationPath: Type-Safe Stack Management

NavigationPath is a type representing the navigation path in NavigationStack. It can store heterogeneous values (AnyHashable) or be used with a specific type via Binding to an array [T: Hashable]. NavigationPath automatically encodes and decodes for state preservation.

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

    var body: some View {
        NavigationStack(path: $path) {
            HomeView()
                .navigationDestination(for: String.self) { value in
                    DetailView(id: value)
                }
                .navigationDestination(for: Int.self) { value in
                    NumberView(number: value)
                }
        }
    }

    func goToRoot() {
        path.removeLast(path.count)
    }

    func pushDeepLink() {
        path.append("detail_42")
    }
}

Heterogeneous stack: NavigationPath can contain values of different types if they implement Hashable. For example, the first screen may accept a String (ID), the second an Int (number), the third a custom enum Route. Each type registers a separate .navigationDestination for display.

Codable support: NavigationPath implements Codable if all values in the path are also Codable + Hashable. This allows saving and restoring navigation state when restarting the app or entering the background.

NavigationDestination: Registering Destination Screens

.navigationDestination(for:destination:) — a modifier that registers a destination View for a specific data type. When NavigationLink puts a value of this type into the path, SwiftUI automatically finds the corresponding .navigationDestination and creates the screen.

enum AppRoute: Hashable {
    case profile(UserID)
    case settings
    case about
}

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

    var body: some View {
        NavigationStack(path: $path) {
            HomeView()
                .navigationDestination(for: AppRoute.self) { route in
                    switch route {
                    case .profile(let id):
                        ProfileView(userId: id)
                    case .settings:
                        SettingsView()
                    case .about:
                        AboutView()
                    }
                }
        }
    }
}

// Navigate: path.append(AppRoute.profile("user_123"))

Important rule: .navigationDestination must be applied to a View that is inside NavigationStack, and before NavigationLink places a value into the path. It is usually added to the root View or a section container. If no .navigationDestination is found for the value’s type, the transition will not occur.

According to SwiftUI Engineering (2023), .navigationDestination can be registered at different levels of the hierarchy. SwiftUI looks for the nearest matching destination during navigation. This allows overriding the destination for one type in different parts of the application.

NavigationStack Usage Patterns

Pattern 1: Navigation via enum Route. Define an enum with associated values for all screens in the application. Use one .navigationDestination for AppRoute and a switch for routing. This provides a single source of truth for all possible transitions in the application.

struct StoreView: View {
    @State private var path: [ProductRoute] = []

    var body: some View {
        NavigationStack(path: $path) {
            ProductGrid()
                .navigationDestination(for: ProductRoute.self) { route in
                    switch route {
                    case .detail(let product):
                        ProductDetail(product: product)
                    case .reviews(let productId):
                        ReviewsView(productId: productId)
                    }
                }
        }
    }
}

enum ProductRoute: Hashable {
    case detail(Product)
    case reviews(String)
}

Pattern 2: Programmatic navigation and deep linking. NavigationStack allows programmatic stack management: adding, removing screens, and returning to the root. This is necessary for push notifications, deep links, and restoring navigation after restart.

Pattern 3: Array of types instead of NavigationPath. If all screens use the same type (e.g., String or a custom enum), use Binding to [T]. This provides stronger typing and better performance than NavigationPath. NavigationPath is justified for heterogeneous stacks with different screen types.

According to Point-Free (2024), NavigationStack with enum Route is the preferred way to organize navigation in SwiftUI applications. It makes all possible transitions explicit, type-safe, and testable, which is especially important for large projects with dozens of screens.