| name | navigation-patterns |
| description | SwiftUI navigation architecture patterns including NavigationStack, NavigationSplitView, TabView, programmatic navigation, and custom transitions. Use when reviewing or building navigation, fixing navigation bugs, or architecting app flow. |
| allowed-tools | ["Read","Glob","Grep"] |
| last_verified | "2026-07-16T00:00:00.000Z" |
| review_by | "2027-06-22T00:00:00.000Z" |
| os_version | iOS 27 / macOS 27 |
Navigation Patterns
Comprehensive guide for SwiftUI navigation architecture on iOS, iPadOS, and macOS. Covers the modern navigation APIs (iOS 16+/macOS 13+) with patterns for common and advanced use cases.
When This Skill Activates
- User is building or reviewing navigation architecture
- User has navigation-related bugs (stack not updating, back button issues, state loss)
- User asks about NavigationStack, NavigationSplitView, TabView, or NavigationPath
- User needs programmatic navigation (push, pop, pop-to-root)
- User is implementing deep linking that connects to navigation
- User asks about navigation transitions or animations
- User is choosing between navigation approaches for their app
Decision Tree
Use this to pick the right navigation container:
What is the app structure?
│
├─ Flat sections (3-5 top-level areas)
│ └─ TabView → see tab-view.md
│
├─ Hierarchical drill-down (list → detail)
│ └─ NavigationStack → see navigation-stack.md
│
├─ Sidebar + content (macOS / iPad)
│ ├─ Two columns → NavigationSplitView → see navigation-split-view.md
│ └─ Three columns → NavigationSplitView → see navigation-split-view.md
│
└─ Combined (tabs with drill-down, sidebar with stacks)
└─ TabView + NavigationStack per tab
OR NavigationSplitView + NavigationStack in detail
Quick Reference
| Pattern | Container | Min OS | Reference |
|---|
| Simple drill-down | NavigationStack | iOS 16 | navigation-stack.md |
| Value-based links | NavigationLink(value:) | iOS 16 | navigation-stack.md |
| Programmatic push/pop | NavigationPath | iOS 16 | programmatic-navigation.md |
| Pop to root | path = NavigationPath() | iOS 16 | programmatic-navigation.md |
| State restoration | NavigationPath.CodableRepresentation | iOS 16 | programmatic-navigation.md |
| Two-column layout | NavigationSplitView | iOS 16 | navigation-split-view.md |
| Three-column layout | NavigationSplitView | iOS 16 | navigation-split-view.md |
| Column visibility | NavigationSplitViewVisibility | iOS 16 | navigation-split-view.md |
| Tab bar | TabView | iOS 13 | tab-view.md |
| Customizable tabs | Tab + TabView | iOS 18 | tab-view.md |
| Sidebar tabs (iPad) | .tabViewStyle(.sidebarAdaptable) | iOS 18 | tab-view.md |
| Zoom transition | .navigationTransition(.zoom) | iOS 18 | navigation-transitions.md |
| Custom transitions | NavigationTransition | iOS 18 | navigation-transitions.md |
Navigation Design Rules (WWDC22)
The container APIs above decide how navigation is built; these rules decide whether it's designed right.
Tab bars
- Tabs are top-level content categories, not arbitrary groupings — balance features across tabs so each carries real weight.
- ❌ Never auto-switch tabs in response to an action taken in another tab — confirm in place instead.
Push vs modal
- Push (right-to-left) = traversing the app's hierarchy. Modal (slides up — covering the tab bar is by design) = a self-contained task apart from the hierarchy.
- Modals come in three types: simple task, multi-step task, full-screen content.
- Limit modals presented over modals — each stacked layer buries the user deeper in transient state.
Wayfinding
- Nav bar title = the current location; the back button shows the previous screen's title.
The Three Cookbook Recipes (WWDC22)
Nearly every app is one of these three shapes. Pick one per scene, then lift its navigation state.
- Pushable stack —
NavigationStack(path:) + NavigationLink(value:) + .navigationDestination(for:). Pop-to-root is path.removeAll(); a deep link is just assigning the path.
- Multi-column without stacks —
NavigationSplitView + List(selection:) in each leading column. Value links auto-drive the next column's selection, so programmatic navigation is setting the selection value.
- Split + stack (Photos-style) —
NavigationSplitView with a NavigationStack(path:) inside the detail column: sidebar selection picks the collection, the stack drills into it.
Rules that make the recipes hold up:
- Build with
NavigationSplitView even for iPhone-first apps — it auto-collapses to a single stack in compact width, and iPad/Mac layouts come free.
- Lift navigation state: exactly one bound
path/selection per container. That single source of truth is what makes pop-to-root, deep links, and restoration one-line operations.
State restoration: persist through @SceneStorage("navigation") plus a .task that restores once on appear, then streams subsequent path changes back into storage.
Process
1. Identify Navigation Needs
Read the user's code or requirements to determine:
- App structure (flat, hierarchical, sidebar-based)
- Target platforms (iOS only, iPad adaptive, macOS)
- Whether programmatic navigation is needed
- Deep linking requirements
2. Load Relevant Reference Files
Based on the need, read from this directory:
navigation-stack.md — NavigationStack, NavigationLink, navigationDestinationnavigation-split-view.md — Two/three column layouts, column control, adaptive behaviortab-view.md — TabView, iOS 18 customizable tabs, sidebar modeprogrammatic-navigation.md — NavigationPath, state restoration, coordinators, pop-to-rootnavigation-transitions.md — Custom push/pop transitions (iOS 18+)
3. Review or Recommend
Apply patterns from the reference files. Check for common mistakes:
4. Cross-Reference
- For deep linking URL handling, see
generators/deep-linking/ skill
- For navigation animations, see
design/animation-patterns/transitions.md
- For macOS sidebar patterns, see
macos/ui-review-tahoe/swiftui-macos.md
References
