navigation

Navigation Pattern Rules

Pattern Selection Guide

Pattern	When to Use
NavigationStack	Hierarchical drill-down (list → detail → edit)
TabView with Tab API	3+ distinct top-level peer sections
.sheet(item:)	Creation forms, secondary actions, settings
.fullScreenCover	Immersive experiences (media player, onboarding)
NavigationStack + .sheet	Most MVPs with 2-4 features

NavigationStack

Use for hierarchical navigation with a back button:

NavigationStack {
    List(items) { item in
        NavigationLink(value: item) {
            ItemRow(item: item)
        }
    }
    .navigationDestination(for: Item.self) { item in
        ItemDetailView(item: item)
    }
    .navigationTitle("Items")
}

TabView with Tab API

Use when the app has 3+ distinct, peer-level sections:

TabView {
    Tab("Home", systemImage: "house") {
        HomeView()
    }
    Tab("Search", systemImage: "magnifyingglass") {
        SearchView()
    }
    Tab("Profile", systemImage: "person") {
        ProfileView()
    }
}

Sheets

Choose the right sheet variant based on context:

• .sheet(item:) — for editing or viewing an existing item (the item drives the sheet)
• .sheet(isPresented:) — acceptable for creation forms and simple actions (no item yet)

// Editing/viewing an existing item — use item-driven
@State private var editingItem: Item?

.sheet(item: $editingItem) { item in
    EditItemView(item: item)
}

// Creating a new item — isPresented is fine
@State private var showAddItem = false

.sheet(isPresented: $showAddItem) {
    AddItemView()
}

Full Screen Cover

Use for immersive content that should cover the entire screen:

@State private var showOnboarding = false

.fullScreenCover(isPresented: $showOnboarding) {
    OnboardingView()
}

Type-Safe Routing

Always use navigationDestination(for:) for type-safe routing:

// Define route types
.navigationDestination(for: Note.self) { note in
    NoteDetailView(note: note)
}
.navigationDestination(for: Category.self) { category in
    CategoryView(category: category)
}