rshankras/navigation-patterns

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.

1. Pushable stack — NavigationStack(path:) + NavigationLink(value:) + .navigationDestination(for:). Pop-to-root is path.removeAll(); a deep link is just assigning the path.
2. 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.
3. 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, navigationDestination
• navigation-split-view.md — Two/three column layouts, column control, adaptive behavior
• tab-view.md — TabView, iOS 18 customizable tabs, sidebar mode
• programmatic-navigation.md — NavigationPath, state restoration, coordinators, pop-to-root
• navigation-transitions.md — Custom push/pop transitions (iOS 18+)

3. Review or Recommend

Apply patterns from the reference files. Check for common mistakes:

• [ ] Using deprecated NavigationView instead of NavigationStack/NavigationSplitView
• [ ] Using NavigationLink(destination:) instead of NavigationLink(value:) + .navigationDestination
• [ ] Placing NavigationStack in a sidebar/content column of NavigationSplitView (a stack belongs only in the detail column — Recipe 3)
• [ ] .navigationDestination attached inside a lazy container (destination may never register)
• [ ] Missing .navigationDestination registration for a value type
• [ ] NavigationPath not @State or not in the right scope
• [ ] Multiple NavigationStacks competing for the same navigation context
• [ ] Hard-coding navigation instead of using NavigationPath for programmatic control
• [ ] Not handling deep links through the navigation system

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

• NavigationStack
• NavigationSplitView
• NavigationPath
• TabView
• Migrating to new navigation types