SwiftUI Navigation Patterns — NavigationStack, Deep Linking & Tab Routing (2026)

Why Navigation Is the Hardest Part of SwiftUI

Navigation is where most SwiftUI projects go sideways. Not because the APIs are bad — Apple has actually done a good job since the NavigationStack rewrite in iOS 16 — but because navigation touches everything. It connects your architecture to your UI. It determines how deep linking works. It decides whether your app feels like a polished product or a prototype held together with duct tape.

The old NavigationView with NavigationLink(destination:) was fine for tutorials. It fell apart the moment you needed programmatic navigation, deep links, or anything beyond a simple push-and-pop stack. Apple knew it, which is why they replaced it entirely with NavigationStack and value-based navigation in iOS 16.

This guide covers every navigation pattern you will need in a production SwiftUI app. I am writing the code I actually use in shipping apps — not simplified playground examples that break the moment you add a second tab or handle a push notification deep link.

NavigationStack Basics

NavigationStack is the foundation. It replaces NavigationView (now deprecated) and gives you a proper stack-based navigation model with programmatic control. The simplest form looks like this:

import SwiftUI

struct ContentView: View {
    var body: some View {
        NavigationStack {
            List {
                NavigationLink("Profile", value: "profile")
                NavigationLink("Settings", value: "settings")
            }
            .navigationTitle("Home")
            .navigationDestination(for: String.self) { value in
                switch value {
                case "profile":
                    ProfileView()
                case "settings":
                    SettingsView()
                default:
                    Text("Unknown destination")
                }
            }
        }
    }
}

The key difference from the old API: NavigationLink now takes a value, not a destination view. The destination is resolved lazily by navigationDestination(for:). This means the destination view is not created until the user actually navigates — a massive performance win for large lists.

Rule of thumb: Never use the deprecated NavigationLink(destination:)initializer. Always use the value-based NavigationLink(_:value:) paired with navigationDestination(for:).

NavigationPath for Type-Erased Navigation

When your navigation stack needs to handle multiple types of destinations, NavigationPathis the tool. It is a type-erased collection that can hold any Hashable value, letting you push different route types onto the same stack.

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

    var body: some View {
        NavigationStack(path: $path) {
            HomeView(path: $path)
                .navigationDestination(for: UserRoute.self) { route in
                    switch route {
                    case .profile(let userID):
                        ProfileView(userID: userID)
                    case .editProfile:
                        EditProfileView()
                    case .followers(let userID):
                        FollowersView(userID: userID)
                    }
                }
                .navigationDestination(for: ContentRoute.self) { route in
                    switch route {
                    case .postDetail(let postID):
                        PostDetailView(postID: postID)
                    case .comments(let postID):
                        CommentsView(postID: postID)
                    case .category(let name):
                        CategoryView(name: name)
                    }
                }
        }
    }
}

You can register multiple navigationDestination(for:) modifiers for different types. SwiftUI matches the pushed value to the correct destination handler automatically. This is how you build complex navigation trees without a single massive switch statement.

Type-Safe Route Enums

Stringly-typed navigation is a bug factory. Use enums to define every possible route in your app. This gives you compile-time safety, exhaustive switch coverage, and associated values for passing data between views.

// Routes/UserRoute.swift
enum UserRoute: Hashable {
    case profile(userID: UUID)
    case editProfile
    case followers(userID: UUID)
    case following(userID: UUID)
    case settings
}

// Routes/ContentRoute.swift
enum ContentRoute: Hashable {
    case postDetail(postID: UUID)
    case comments(postID: UUID)
    case category(name: String)
    case search(query: String)
    case trending
}

// Routes/AppRoute.swift — unified route for deep linking
enum AppRoute: Hashable {
    case user(UserRoute)
    case content(ContentRoute)
    case onboarding
    case paywall
}

Every route is Hashable so it can be pushed onto a NavigationPath or a typed [Route] array. Associated values carry the data each destination needs. No dictionaries, no stringly-typed keys, no runtime crashes because someone misspelled a route name.

Programmatic Navigation with @State Path

The real power of NavigationStack is programmatic control. By binding a @State array or NavigationPath to the stack, you can push, pop, and replace the entire stack from anywhere in your code. This is what makes deep linking, notification handling, and coordinator patterns possible.

struct HomeView: View {
    @Binding var path: NavigationPath

    var body: some View {
        List {
            // Value-based NavigationLink (pushes automatically)
            NavigationLink("My Profile", value: UserRoute.profile(userID: currentUserID))

            // Programmatic push via button
            Button("Open Trending") {
                path.append(ContentRoute.trending)
            }

            // Push multiple screens at once (deep link simulation)
            Button("Jump to Post Comments") {
                path.append(ContentRoute.postDetail(postID: somePostID))
                path.append(ContentRoute.comments(postID: somePostID))
            }
        }
        .navigationTitle("Home")
        .toolbar {
            ToolbarItem(placement: .topBarTrailing) {
                Button("Settings") {
                    path.append(UserRoute.settings)
                }
            }
        }
    }

    // Pop to root
    func popToRoot() {
        path = NavigationPath()
    }

    // Pop one level
    func popOne() {
        if path.count > 0 {
            path.removeLast()
        }
    }
}

Three things to notice here. First, you can push multiple routes in sequence to build a deep navigation stack instantly — this is exactly how deep links work. Second, popping to root is just assigning a new empty path. Third, you can mix NavigationLink (user-initiated) and programmatic pushes (code-initiated) in the same stack without conflict.

Coordinator Pattern for Complex Navigation

For apps with more than a few screens, managing navigation state directly in views gets messy. The coordinator pattern extracts navigation logic into a dedicated object. In SwiftUI, this is an @Observable class that owns the NavigationPath and exposes semantic navigation methods.

// Navigation/AppCoordinator.swift
import SwiftUI

@Observable
@MainActor
final class AppCoordinator {
    var homePath = NavigationPath()
    var searchPath = NavigationPath()
    var profilePath = NavigationPath()

    // Currently selected tab
    var selectedTab: AppTab = .home

    // Sheet presentation
    var presentedSheet: AppSheet?

    // MARK: - Navigation Methods

    func navigateToProfile(userID: UUID) {
        selectedTab = .profile
        profilePath = NavigationPath()
        profilePath.append(UserRoute.profile(userID: userID))
    }

    func navigateToPost(postID: UUID) {
        selectedTab = .home
        homePath.append(ContentRoute.postDetail(postID: postID))
    }

    func navigateToPostComments(postID: UUID) {
        selectedTab = .home
        homePath.append(ContentRoute.postDetail(postID: postID))
        homePath.append(ContentRoute.comments(postID: postID))
    }

    func showPaywall() {
        presentedSheet = .paywall
    }

    func showSettings() {
        presentedSheet = .settings
    }

    func popToRoot(tab: AppTab) {
        switch tab {
        case .home: homePath = NavigationPath()
        case .search: searchPath = NavigationPath()
        case .profile: profilePath = NavigationPath()
        }
    }

    func resetAll() {
        homePath = NavigationPath()
        searchPath = NavigationPath()
        profilePath = NavigationPath()
        selectedTab = .home
        presentedSheet = nil
    }
}

// Supporting types
enum AppTab: Hashable {
    case home, search, profile
}

enum AppSheet: Identifiable {
    case paywall, settings, compose

    var id: Self { self }
}

The coordinator is the single source of truth for all navigation state. Views call coordinator methods instead of mutating paths directly. This makes it trivial to handle deep links, push notifications, and cross-tab navigation — the coordinator knows how to get from anywhere to anywhere.

Inject the coordinator through the SwiftUI environment so every view can access it:

// App entry point
@main
struct MyApp: App {
    @State private var coordinator = AppCoordinator()

    var body: some Scene {
        WindowGroup {
            MainTabView()
                .environment(coordinator)
        }
    }
}

Deep Linking: URL Schemes and Universal Links

Deep linking is where navigation architecture either pays off or collapses. If you built your navigation with type-safe routes and a coordinator, deep linking is straightforward. If you scattered navigation state across dozens of views, deep linking will be a nightmare.

URL Scheme Registration

First, register your URL scheme in your Info.plist or Xcode target settings. Then parse incoming URLs into your route enums:

// DeepLink/DeepLinkHandler.swift
import Foundation

struct DeepLinkHandler {
    /// Parse a URL into an AppRoute
    /// Supports: myapp://profile/UUID, myapp://post/UUID, myapp://post/UUID/comments, etc.
    static func parse(url: URL) -> AppRoute? {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
            return nil
        }

        let pathParts = components.path
            .split(separator: "/")
            .map(String.init)

        switch pathParts.first {
        case "profile":
            guard pathParts.count >= 2,
                  let userID = UUID(uuidString: pathParts[1]) else {
                return nil
            }
            return .user(.profile(userID: userID))

        case "post":
            guard pathParts.count >= 2,
                  let postID = UUID(uuidString: pathParts[1]) else {
                return nil
            }
            if pathParts.count >= 3 && pathParts[2] == "comments" {
                return .content(.comments(postID: postID))
            }
            return .content(.postDetail(postID: postID))

        case "settings":
            return .user(.settings)

        case "category":
            guard pathParts.count >= 2 else { return nil }
            return .content(.category(name: pathParts[1]))

        case "search":
            let query = components.queryItems?
                .first(where: { $0.name == "q" })?.value ?? ""
            return .content(.search(query: query))

        case "paywall":
            return .paywall

        default:
            return nil
        }
    }
}

Deep Link URL Scheme Examples

Here is a reference table of URL patterns and how they map to your app routes:

Handling Deep Links in Your App

Wire the deep link handler into your app entry point and let the coordinator do the routing:

@main
struct MyApp: App {
    @State private var coordinator = AppCoordinator()

    var body: some Scene {
        WindowGroup {
            MainTabView()
                .environment(coordinator)
                .onOpenURL { url in
                    handleDeepLink(url)
                }
        }
    }

    private func handleDeepLink(_ url: URL) {
        guard let route = DeepLinkHandler.parse(url: url) else {
            print("Unrecognized deep link: \(url)")
            return
        }

        switch route {
        case .user(let userRoute):
            switch userRoute {
            case .profile(let userID):
                coordinator.navigateToProfile(userID: userID)
            case .settings:
                coordinator.showSettings()
            default:
                coordinator.selectedTab = .profile
                coordinator.profilePath.append(userRoute)
            }

        case .content(let contentRoute):
            switch contentRoute {
            case .postDetail(let postID):
                coordinator.navigateToPost(postID: postID)
            case .comments(let postID):
                coordinator.navigateToPostComments(postID: postID)
            default:
                coordinator.selectedTab = .home
                coordinator.homePath.append(contentRoute)
            }

        case .paywall:
            coordinator.showPaywall()

        case .onboarding:
            coordinator.resetAll()
        }
    }
}

For Universal Links (HTTPS URLs that open your app), the process is the same. You set up your apple-app-site-association file on your server, add the Associated Domains entitlement in Xcode, and the same .onOpenURL handler receives the Universal Link URL. The parser works identically because you are parsing the path components the same way.

TabView with Independent NavigationStacks

The most common architecture mistake in multi-tab SwiftUI apps: wrapping a single NavigationStack around the TabView. This makes the tab bar disappear when you push a view, which is almost never what you want. The correct pattern is one NavigationStack per tab.

struct MainTabView: View {
    @Environment(AppCoordinator.self) private var coordinator

    var body: some View {
        @Bindable var coordinator = coordinator

        TabView(selection: $coordinator.selectedTab) {
            // MARK: - Home Tab
            NavigationStack(path: $coordinator.homePath) {
                HomeView()
                    .navigationDestination(for: ContentRoute.self) { route in
                        switch route {
                        case .postDetail(let postID):
                            PostDetailView(postID: postID)
                        case .comments(let postID):
                            CommentsView(postID: postID)
                        case .category(let name):
                            CategoryView(name: name)
                        case .search(let query):
                            SearchResultsView(query: query)
                        case .trending:
                            TrendingView()
                        }
                    }
                    .navigationDestination(for: UserRoute.self) { route in
                        userDestination(for: route)
                    }
            }
            .tabItem {
                Label("Home", systemImage: "house.fill")
            }
            .tag(AppTab.home)

            // MARK: - Search Tab
            NavigationStack(path: $coordinator.searchPath) {
                SearchView()
                    .navigationDestination(for: ContentRoute.self) { route in
                        contentDestination(for: route)
                    }
                    .navigationDestination(for: UserRoute.self) { route in
                        userDestination(for: route)
                    }
            }
            .tabItem {
                Label("Search", systemImage: "magnifyingglass")
            }
            .tag(AppTab.search)

            // MARK: - Profile Tab
            NavigationStack(path: $coordinator.profilePath) {
                ProfileView()
                    .navigationDestination(for: UserRoute.self) { route in
                        userDestination(for: route)
                    }
                    .navigationDestination(for: ContentRoute.self) { route in
                        contentDestination(for: route)
                    }
            }
            .tabItem {
                Label("Profile", systemImage: "person.fill")
            }
            .tag(AppTab.profile)
        }
        .sheet(item: $coordinator.presentedSheet) { sheet in
            sheetContent(for: sheet)
        }
    }

    // MARK: - Destination Builders

    @ViewBuilder
    private func contentDestination(for route: ContentRoute) -> some View {
        switch route {
        case .postDetail(let postID): PostDetailView(postID: postID)
        case .comments(let postID): CommentsView(postID: postID)
        case .category(let name): CategoryView(name: name)
        case .search(let query): SearchResultsView(query: query)
        case .trending: TrendingView()
        }
    }

    @ViewBuilder
    private func userDestination(for route: UserRoute) -> some View {
        switch route {
        case .profile(let userID): ProfileView(userID: userID)
        case .editProfile: EditProfileView()
        case .followers(let userID): FollowersView(userID: userID)
        case .following(let userID): FollowingView(userID: userID)
        case .settings: SettingsView()
        }
    }

    @ViewBuilder
    private func sheetContent(for sheet: AppSheet) -> some View {
        switch sheet {
        case .paywall: PaywallView()
        case .settings: SettingsView()
        case .compose: ComposeView()
        }
    }
}

Each tab has its own NavigationStack with its own path. When the user switches tabs, each tab remembers exactly where they were. The coordinator can push to any tab from anywhere. Deep links switch to the correct tab and push the right screen. This is the architecture that every production tab-based iOS app needs.

Pro tip: Extract your navigationDestination handlers into helper methods (like contentDestination and userDestination above) to avoid duplicating the same switch statements across tabs.

Sheet and FullScreenCover Presentation

Not everything should be a push navigation. Modal sheets and full-screen covers are better for self-contained flows (compose, settings, paywall) that have their own independent context. SwiftUI provides two modal presentation styles:

• .sheet() — Slides up as a card. User can dismiss by swiping down. Best for secondary tasks.
• .fullScreenCover() — Takes over the entire screen. Must be dismissed programmatically. Best for onboarding, auth, and immersive flows.

struct ProfileView: View {
    @State private var showEditSheet = false
    @State private var showOnboarding = false
    @Environment(AppCoordinator.self) private var coordinator

    var body: some View {
        Form {
            Section("Account") {
                Button("Edit Profile") {
                    showEditSheet = true
                }
                Button("Upgrade to Pro") {
                    coordinator.showPaywall()
                }
            }
        }
        .sheet(isPresented: $showEditSheet) {
            NavigationStack {
                EditProfileView()
                    .toolbar {
                        ToolbarItem(placement: .cancellationAction) {
                            Button("Cancel") { showEditSheet = false }
                        }
                        ToolbarItem(placement: .confirmationAction) {
                            Button("Save") {
                                // Save and dismiss
                                showEditSheet = false
                            }
                        }
                    }
            }
        }
        .fullScreenCover(isPresented: $showOnboarding) {
            OnboardingView {
                showOnboarding = false
            }
        }
    }
}

An important pattern: when a sheet needs its own navigation (push screens within the sheet), wrap the sheet content in its own NavigationStack. This gives the sheet an independent navigation stack that does not interfere with the parent screen.

Comparing Navigation Approaches

Here is a side-by-side comparison of every navigation approach available in SwiftUI, so you can pick the right one for your project:

My recommendation for new projects: start with NavigationStack + typed path. Once you add a second tab or need deep linking, introduce the Coordinator pattern. Use sheets for secondary flows. This combination covers every navigation need in a production iOS app.

Navigation State Restoration

State restoration lets your app re-open to exactly where the user left off. This is critical for apps where users build up navigation stacks — they expect to return to the same screen after the system kills your app in the background.

NavigationPath conforms to Codable (when all its elements are Codable), which means you can serialize and deserialize the entire navigation stack:

// Navigation/NavigationStateManager.swift
import SwiftUI

@Observable
@MainActor
final class NavigationStateManager {
    private let defaults = UserDefaults.standard
    private let homePathKey = "nav.homePath"
    private let selectedTabKey = "nav.selectedTab"

    func save(coordinator: AppCoordinator) {
        // Save the selected tab
        if let tabData = try? JSONEncoder().encode(coordinator.selectedTab) {
            defaults.set(tabData, forKey: selectedTabKey)
        }

        // Save home path (NavigationPath.CodableRepresentation)
        if let representation = coordinator.homePath.codable {
            if let data = try? JSONEncoder().encode(representation) {
                defaults.set(data, forKey: homePathKey)
            }
        }
    }

    func restore(into coordinator: AppCoordinator) {
        // Restore selected tab
        if let tabData = defaults.data(forKey: selectedTabKey),
           let tab = try? JSONDecoder().decode(AppTab.self, from: tabData) {
            coordinator.selectedTab = tab
        }

        // Restore home path
        if let data = defaults.data(forKey: homePathKey),
           let representation = try? JSONDecoder().decode(
               NavigationPath.CodableRepresentation.self, from: data
           ) {
            coordinator.homePath = NavigationPath(representation)
        }
    }
}

Call save() in scenePhase changes and restore() on app launch. Make sure all your route enums conform to Codable for this to work:

@main
struct MyApp: App {
    @State private var coordinator = AppCoordinator()
    @Environment(\.scenePhase) private var scenePhase
    private let stateManager = NavigationStateManager()

    var body: some Scene {
        WindowGroup {
            MainTabView()
                .environment(coordinator)
                .onOpenURL { url in
                    handleDeepLink(url)
                }
        }
        .onChange(of: scenePhase) { _, newPhase in
            if newPhase == .background {
                stateManager.save(coordinator: coordinator)
            }
        }
        .task {
            stateManager.restore(into: coordinator)
        }
    }
}

Passing Data Between Views

SwiftUI gives you several mechanisms for passing data through navigation. The right choice depends on the relationship between the source and destination views.

Via Route Associated Values (Preferred)

The cleanest approach: embed the data (or an identifier to fetch it) directly in the route enum. The destination view receives it through navigationDestination(for:).

// Push with data embedded in the route
path.append(ContentRoute.postDetail(postID: post.id))

// Destination receives the data
.navigationDestination(for: ContentRoute.self) { route in
    switch route {
    case .postDetail(let postID):
        PostDetailView(postID: postID)  // View fetches full post by ID
    // ...
    }
}

Via @Environment for Global State

For data that many views need (current user, theme, DI container), use the SwiftUI environment. Do not use it for screen-specific data.

// Inject globally
.environment(authManager)

// Access from any view
@Environment(AuthManager.self) private var authManager

Via @Binding for Parent-Child Communication

When a child view needs to mutate data owned by its parent (like an edit sheet modifying a profile), use @Binding. The parent owns the state, the child reads and writes it.

struct EditProfileView: View {
    @Binding var profile: UserProfile
    @Environment(\.dismiss) private var dismiss

    var body: some View {
        Form {
            TextField("Display Name", text: $profile.displayName)
            TextField("Bio", text: $profile.bio)
        }
        .toolbar {
            ToolbarItem(placement: .confirmationAction) {
                Button("Save") { dismiss() }
            }
        }
    }
}

Important: Do not pass large objects through route associated values. Pass an identifier (like a UUID) and let the destination view fetch the full object from a repository or cache. This keeps your navigation path serializable and avoids stale data.

Common Navigation Pitfalls

After building dozens of SwiftUI apps and reviewing many more, these are the navigation mistakes I see most often:

Pitfall 1: NavigationStack Outside TabView

Wrapping TabView in a single NavigationStack causes the tab bar to disappear on push navigation. Always put one NavigationStack insideeach tab.

// BAD: Tab bar disappears on push
NavigationStack {
    TabView {
        HomeView()
        ProfileView()
    }
}

// GOOD: Each tab has its own stack
TabView {
    NavigationStack { HomeView() }
        .tabItem { Label("Home", systemImage: "house") }
    NavigationStack { ProfileView() }
        .tabItem { Label("Profile", systemImage: "person") }
}

Pitfall 2: Destination View Initializer Side Effects

With value-based navigation, destination views are created lazily. But if your view initializer triggers network calls or heavy computation, it still fires when SwiftUI resolves the destination. Move side effects to .task or .onAppear.

// BAD: Network call in init
struct PostDetailView: View {
    @State private var post: Post?

    init(postID: UUID) {
        // This fires during navigation resolution
        Task { post = try await fetchPost(postID) }  // Wrong!
    }
}

// GOOD: Side effects in .task
struct PostDetailView: View {
    let postID: UUID
    @State private var post: Post?

    var body: some View {
        Group {
            if let post {
                PostContent(post: post)
            } else {
                ProgressView()
            }
        }
        .task {
            post = try? await fetchPost(postID)
        }
    }
}

Pitfall 3: Not Making Route Enums Codable

If you plan to use NavigationPath (type-erased), your route enums must be both Hashable and Codable. Without Codable, NavigationPath.codable returns nil, and state restoration silently fails.

// Always include both protocols
enum ContentRoute: Hashable, Codable {
    case postDetail(postID: UUID)
    case comments(postID: UUID)
    case category(name: String)
    case search(query: String)
    case trending
}

Pitfall 4: Too Many navigationDestination Modifiers

SwiftUI logs a runtime warning if you register multiple navigationDestinationmodifiers for the same type in the same stack. Keep one modifier per type, at the top level of each NavigationStack.

Pitfall 5: Forgetting dismiss() in Sheets

Sheets need an explicit dismiss mechanism. Users can swipe to dismiss, but programmatic dismissal (after saving, for example) requires the @Environment(\.dismiss)action.

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

    var body: some View {
        VStack {
            // ... form content
            Button("Publish") {
                publishPost()
                dismiss()  // Always dismiss after action
            }
        }
    }
}

Full Architecture Example: Putting It All Together

Here is the complete file structure for a production navigation architecture. Every file shown in this guide fits into this structure:

MyApp/
├── App/
│   └── MyApp.swift                     // Entry point, deep link handler
├── Navigation/
│   ├── AppCoordinator.swift            // Central navigation state
│   ├── NavigationStateManager.swift    // State restoration
│   └── DeepLinkHandler.swift           // URL parsing
├── Routes/
│   ├── AppRoute.swift                  // Top-level route enum
│   ├── UserRoute.swift                 // User-related routes
│   └── ContentRoute.swift              // Content-related routes
├── Views/
│   ├── MainTabView.swift               // TabView + NavigationStacks
│   ├── Home/
│   │   ├── HomeView.swift
│   │   ├── PostDetailView.swift
│   │   └── TrendingView.swift
│   ├── Search/
│   │   ├── SearchView.swift
│   │   └── SearchResultsView.swift
│   ├── Profile/
│   │   ├── ProfileView.swift
│   │   ├── EditProfileView.swift
│   │   └── FollowersView.swift
│   └── Sheets/
│       ├── PaywallView.swift
│       ├── SettingsView.swift
│       └── ComposeView.swift
├── ViewModels/
│   └── ...
├── Models/
│   └── ...
└── Services/
    └── ...

The navigation layer is completely separated from your business logic. The coordinator does not know what a PostDetailView does — it just knows how to get there. Views do not know about other views — they just push route values. And the deep link handler does not know about the UI at all — it just parses URLs into routes.

Testing Navigation

Because the coordinator is a plain @Observable class, you can test navigation logic without any UI:

@MainActor
final class AppCoordinatorTests: XCTestCase {
    private var coordinator: AppCoordinator!

    override func setUp() {
        coordinator = AppCoordinator()
    }

    func testNavigateToProfileSwitchesTab() {
        coordinator.navigateToProfile(userID: UUID())
        XCTAssertEqual(coordinator.selectedTab, .profile)
        XCTAssertEqual(coordinator.profilePath.count, 1)
    }

    func testNavigateToPostCommentsPushesTwoScreens() {
        let postID = UUID()
        coordinator.navigateToPostComments(postID: postID)
        XCTAssertEqual(coordinator.selectedTab, .home)
        XCTAssertEqual(coordinator.homePath.count, 2)
    }

    func testPopToRootClearsPath() {
        coordinator.homePath.append(ContentRoute.trending)
        coordinator.homePath.append(ContentRoute.postDetail(postID: UUID()))
        coordinator.popToRoot(tab: .home)
        XCTAssertEqual(coordinator.homePath.count, 0)
    }

    func testResetAllClearsEverything() {
        coordinator.selectedTab = .profile
        coordinator.profilePath.append(UserRoute.settings)
        coordinator.presentedSheet = .paywall
        coordinator.resetAll()
        XCTAssertEqual(coordinator.selectedTab, .home)
        XCTAssertEqual(coordinator.homePath.count, 0)
        XCTAssertNil(coordinator.presentedSheet)
    }
}

// Deep link parsing tests
final class DeepLinkHandlerTests: XCTestCase {
    func testParseProfileURL() {
        let id = UUID()
        let url = URL(string: "myapp://profile/\(id)")!
        let route = DeepLinkHandler.parse(url: url)
        XCTAssertEqual(route, .user(.profile(userID: id)))
    }

    func testParsePostCommentsURL() {
        let id = UUID()
        let url = URL(string: "myapp://post/\(id)/comments")!
        let route = DeepLinkHandler.parse(url: url)
        XCTAssertEqual(route, .content(.comments(postID: id)))
    }

    func testParseSearchWithQuery() {
        let url = URL(string: "myapp://search?q=swiftui")!
        let route = DeepLinkHandler.parse(url: url)
        XCTAssertEqual(route, .content(.search(query: "swiftui")))
    }

    func testParseInvalidURLReturnsNil() {
        let url = URL(string: "myapp://unknown/path")!
        XCTAssertNil(DeepLinkHandler.parse(url: url))
    }
}

These tests run in milliseconds. No UI testing framework needed. The coordinator is just an object with state — assert that state after calling methods. If you can test your navigation without launching the simulator, your architecture is doing its job.

The Swift Kit: Navigation Architecture Pre-Built

Every pattern in this guide — the coordinator, type-safe route enums, deep link handler, multi-tab navigation stacks, sheet management, and state restoration — is already implemented and battle-tested in The Swift Kit.

Instead of spending a week wiring up navigation infrastructure, you get a production-ready architecture on day one. The coordinator is connected to the onboarding flow, the paywall, the auth system, and every feature screen. Deep links work out of the box. Tab-based navigation with independent stacks is the default. You just add your screens and routes.

• AppCoordinator with typed paths for every tab
• Route enums with Hashable + Codable conformance
• Deep link handler for URL schemes and Universal Links
• Navigation state restoration across app launches
• Sheet management for paywall, settings, and onboarding flows
• MVVM architecture with dependency injection already wired up (see our architecture guide)

For the full picture of what comes pre-built, check our SwiftUI boilerplate guide or see the features page. If you want to start building on solid navigation architecture today, grab The Swift Kit from the pricing page and skip the infrastructure work entirely.