@Observable @MainActor Router in .environment, NavigationStack(path:) over a typed Route enum, navigationDestination(for:) at the stack root, item:-driven sheets and covers, .onOpenURL deep links, NavigationSplitView, per-tab paths, Codable restoration. Use when wiring an App''s navigation, choosing push vs sheet vs fullScreenCover, adding deep links or restoration, migrating off NavigationView, or asked for a router / coordinator in SwiftUI. Runtime bugs → swiftui-interaction-footguns.'The default navigation shape for Apps on this catalog's baseline (apple-platform-targets: iOS 26 / macOS 26, Swift 6 language mode): navigation state is data — a typed route enum in one observable router — so flows are unit-testable (assert on [Route]), deep-linkable (URL → routes is a pure function), and restorable (routes are Codable).
NavigationView or view-payload NavigationLink(destination:)Owns container choice (Stack / SplitView / Tab), route modeling, the router object, deep-link funneling, and restoration. Does NOT own: known interaction bugs in nav components → swiftui-interaction-footguns; injecting the services destination views need → swift-dependency-injection; nav-chrome accessibility → ios-accessibility-engineering.
| App shape | \nContainer | \n
|---|---|
| Single drill-down flow (iPhone-first) | \nNavigationStack(path:) | \n
| 2–5 top-level peer sections | \nTabView + one NavigationStack per tab, each with its own path | \n
| Source list → detail (iPad / Mac) | \nNavigationSplitView; sidebar selection is router state, the detail column hosts its own NavigationStack | \n
Never NavigationView in new code — superseded by NavigationStack / NavigationSplitView since iOS 16, deprecated in the iOS 27 SDK (Xcode 27 warns; the Xcode 26 SDK does not).
enum Route: Hashable, Codable {\n case board(id: UUID) // payloads are IDs, not model objects\n case settings\n}\n\nenum Modal: String, Identifiable { // presentation is NOT navigation\n case paywall, onboarding\n var id: String { rawValue }\n}\n\n@Observable @MainActor\nfinal class Router {\n var path: [Route] = []\n var modal: Modal?\n\n // One pure mapping: URL → navigation state. Unit-test without UI.\n func open(_ url: URL) {\n guard url.scheme == \"myapp\" else { return }\n switch url.host {\n case \"board\": path = [.board(id: UUID(uuidString: url.lastPathComponent) ?? UUID())]\n case \"settings\": path = [.settings]\n default: break\n }\n }\n}\n\n@main struct MyApp: App {\n @State private var router = Router()\n\n var body: some Scene {\n WindowGroup {\n NavigationStack(path: $router.path) {\n HomeView()\n .navigationDestination(for: Route.self) { route in\n switch route { // exhaustive — compiler catches new routes\n case .board(let id): BoardView(id: id)\n case .settings: SettingsView()\n }\n }\n }\n .environment(router)\n .sheet(item: $router.modal) { ModalHost($0) }\n .onOpenURL { router.open($0) }\n }\n }\n}\nRules the shape encodes:
\nNavigationLink(value:) or router.path.append(...); never NavigationLink(destination:) in a path-managed stack (those pushes bypass path, desyncing back-stack, deep links, and restoration).navigationDestination(for:) on the stack's root content, outside lazy containers. Apple's docs (navigationDestination(for:destination:)): \"Do not put a navigation destination modifier inside a 'lazy' container, like List or LazyVStack. … Add the navigation destination modifier outside these containers so that the navigation stack can always see the destination.\"[Route] over NavigationPath — pattern-matchable, exhaustively switched, Codable for free.item:-driven; one optional per presentation kind — sheet, cover, alert. Parallel isPresented: Bools race and can present blank); a presented flow is never a Route case. Which kind → next section.@MainActor (it is UI state; Swift 6 enforces it), routes are Hashable + Codable value types. On Xcode 26's default MainActor isolation (SE-0466) this is implicit for a new project's modules — keep the explicit annotation anyway so the class stays correct if the module later turns default isolation off.\"Where does the user land when this closes?\" is decided by the semantic you pick, not by the destination view. Pick the tag first; the API and its back/dismiss behavior follow.
\n| Semantic | \nAPI | \nDismissal | \niOS / iPadOS | \nmacOS | \n
|---|---|---|---|---|
| push | \nNavigationStack + navigationDestination | \nback pops one level; edge-swipe on by default | \n— | \nsame model, toolbar back | \n
| sheet | \n.sheet(item:) (+ .presentationDetents) | \nswipe-to-dismiss on by default; interactiveDismissDisabled(true) to force completion | \ndetents resize; >1 detent shows the grabber | \nwindow-styled sheet — detents don't drive sizing, size the content itself | \n
| full-screen cover | \n.fullScreenCover(item:) | \nno interactive dismiss; exit only via explicit close | \nopaque, covers everything | \nunavailable on native macOS (Mac Catalyst only) — fall back to push/sheet, see below | \n
| popover | \n.popover | \ntap outside | \ncollapses to a sheet in compact width unless .presentationCompactAdaptation(.popover) | \nalways a true anchored popover | \n
| alert | \n.alert(_:isPresented:presenting:) | \nbutton tap only — no scrim tap, no swipe | \ndata-drive off one optional | \nsame | \n
| dialog | \n.confirmationDialog | \nCancel or tap outside | \nbottom action sheet | \nrendered alert-style | \n
| root-swap | \nconditional root content on @Observable state | \nnone — the outgoing tree is destroyed | \nauth gates, onboarding-done | \nsame | \n
Two contract rules the table enforces:
\nconfirmationDialog or popover, never an .alert, regardless of visual intent.LoginView vs AppView at the root off auth state: success flips the flag and the login tree is destroyed; logout flips it back and tears down the entire app stack (paths, sheets, all of it). Presenting the app over login couples app lifetime to a presentation and turns logout into \"dismiss a modal\" with login still alive underneath.A flow covered by fullScreenCover on iOS ships as a push (or sheet) on macOS — and Close must land on the same screen on both platforms. The trap: dismiss() closes the whole cover, but the pushed variant's naive path.removeLast() pops one level and strands the user mid-flow.
extension Router {\n // One flow, two containers: cover on iOS, push on macOS.\n func startGame(id: UUID) {\n #if os(macOS)\n path.append(.board(id: id))\n #else\n cover = .board(id: id) // .fullScreenCover(item: $router.cover)\n #endif\n }\n func closeGame() { // lands on the hub on BOTH platforms\n #if os(macOS)\n path.removeAll() // pop the whole flow — pop-one strands mid-flow\n #else\n cover = nil\n #endif\n }\n}\nRoute both entry and exit through router methods (as above) so no view ever encodes the platform branch.
\nonOpenURL, universal links, NSUserActivity, notification taps) funnels into router.open(_:) at the scene root — one handler, one mapping function, unit tests assert URL → [Route] directly.scenePhase == .background, JSONEncoder the [Route] into @SceneStorage(a String slot); on launch, decode and assign. Routes that reference store objects carry IDs — resolve at display time and drop routes that no longer resolve instead of crashing.NavigationSplitView: sidebar selection lives in the router; only the detail column hosts a NavigationStack. Don't nest stacks in the sidebar.TabView: the router owns selectedTab and one path per tab — paths kept in per-view @State reset whenever tab identity churns. Selecting the already-active tab popping to root becomes a 2-line router method.swiftui-interaction-footguns..environment: a single owner instead of bindings threaded through N view layers; @Observable keeps invalidation scoped to views that actually read path.NavigationPath: exhaustive switch in navigationDestination means the compiler flags every unhandled route; NavigationPath trades that away for type erasure most single-module apps don't need.NavigationPath + its CodableRepresentation for restoration; you give up exhaustive matching.NavigationStack without router or path is fine; adopt the shape when the second entry point appears, not speculatively.UIViewController interop) → keep coordination at the UIKit layer; don't force a SwiftUI router across the hosting bridge.apple-platform-targets drop-down default) → the shape works unchanged (@Observable, NavigationStack both available; only Liquid Glass presentation chrome is unavailable).@Observable requires iOS 17.0 / macOS 14.0 as its own floor, so this is the lowest target the shape needs no changes on.ObservableObject replaces @Observable for the router.fullScreenCover is available there; the push/sheet fallback is for native (AppKit-based) macOS targets.NavigationView in new code — superseded since iOS 16, deprecated in the iOS 27 SDK (Xcode 27 warns), unpredictable column behavior. Use NavigationStack / NavigationSplitView.navigationDestination(for:) inside List / LazyVStack — the lazy container may not have created the registering view yet, so pushes silently fail (runtime console warning). Register at the stack root.NavigationLink(destination:) into a path-based stack — pushes invisible to path; back-stack count, deep links, and restoration all desync.Modal enum.@State — switching tabs (or any identity churn) resets the stack; paths belong to the router.onOpenURL sprinkled across views — multiple competing handlers; one scene-root handler feeding one mapping function.@MainActor — Swift 6 isolation errors the first time a Task mutates path; annotate the class, not call sites. (Implicit under Xcode 26's default MainActor isolation — SE-0466 — but not every module opts into that default, so annotate explicitly.)Hashable/Codable, goes stale after edits; carry IDs and resolve at display.@Environment(\\.dismiss) read in the presenter — the action applies to the environment where it's declared, never to the content the presenter presented: it pops the presenter itself, closes the sheet the presenter lives in, or (macOS / iPadOS, presenter is a window's root) closes the window; only when the presenter isn't itself presented is it a no-op. Presenter-side closing = nil out the router optional.dismiss() vs dismissAll() as distinct router methods; chain a follow-up presentation in the prior one's onDismiss, never present-while-presenting.NavigationView; no NavigationLink(destination:) inside path-managed stacksRoute enum, Hashable + Codable; payloads are IDs, not model objectsnavigationDestination(for:) registered at the stack root, outside lazy containers@Observable @MainActor router in .environment; all paths (incl. per-tab) live on ititem: off router optionals (one per presentation kind), never a Route case or parallel Bools.onOpenURL at the scene root; URL → [Route] mapping has unit testsswiftui-interaction-footguns — known bugs in the nav components this skill wires togetherswift-dependency-injection — how destination views get their servicesapple-platform-targets — the iOS 26 / macOS 26 baseline this shape assumesios-accessibility-engineering — accessibility of the navigation chromereferences/official-docs.md.