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`

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 inside NavigationSplitView detail (usually wrong)
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

Search AI Tools

navigation-patterns

Install this agent skill to your Project

SKILL.md