---
name: swiftui-navigation
description: "SwiftUI navigation: NavigationStack typed paths, routers, NavigationSplitView, sheets, TabView and Tab API, universal links, URL schemes, Handoff. Use when implementing or reviewing push or programmatic navigation, multi-column layouts, modal sheets, tab bars or deep linking."
metadata:
  source: multi-agent-pipeline
---

# SwiftUI Navigation

Examples target iOS 26 and Swift 6.3. Unless a line says otherwise, each
pattern also runs on iOS 17.

Other skills own the neighbours: app architecture and state management are in
`swiftui-patterns`, stacks, grids and components in
`swiftui-layout-components`.

## NavigationStack

Bind `NavigationStack(path:)` to a `NavigationPath` (or a typed array) in state,
describe destinations with a `Hashable` enum or value type, and map each type
once with `.navigationDestination(for:)`.

```swift
struct TrailListView: View {
    @State private var path = NavigationPath()
    let trails: [Trail]

    var body: some View {
        NavigationStack(path: $path) {
            List(trails) { trail in
                NavigationLink(value: trail) {
                    TrailRow(trail: trail)
                }
            }
            .navigationDestination(for: Trail.self) { trail in
                TrailDetailView(trail: trail)
            }
            .navigationTitle("Trails")
        }
    }
}
```

Driving the stack from code:

| Goal | Code |
| --- | --- |
| Push | `path.append(trail)` |
| Back one level | `path.removeLast()` |
| Back to root | `path = NavigationPath()` |

For anything bigger than one screen, move path and sheet state into a router
object. Give each tab its own router instance and hand it down with
`.environment()`. Keep the destination switch in one place: a single
`.navigationDestination(for:)` block or a shared modifier such as
`withAppRouter()`. The router, per-tab and centralised-mapping patterns are in
[references/navigationstack.md](references/navigationstack.md).

## NavigationSplitView

`NavigationSplitView` gives a sidebar and detail on iPad and Mac and collapses
into a push stack on iPhone.

```swift
struct LibraryView: View {
    @State private var chosen: Album?
    let albums: [Album]

    var body: some View {
        NavigationSplitView {
            List(albums, selection: $chosen) { album in
                NavigationLink(album.title, value: album)
            }
            .navigationTitle("Albums")
        } detail: {
            if let chosen {
                AlbumDetailView(album: chosen)
            } else {
                ContentUnavailableView("No album selected", systemImage: "sidebar.leading")
            }
        }
    }
}
```

### A hand-built second column

When the extra column does not follow the selection, for example an activity
feed that should sit beside whatever the main area shows, build the split
yourself with an `HStack(spacing: 0)`.

```swift
struct WorkspaceView: View {
    @Environment(\.horizontalSizeClass) private var sizeClass
    @AppStorage("showsActivityColumn") private var showsActivity = true

    var body: some View {
        HStack(spacing: 0) {
            MainContentView()
            if sizeClass == .regular && showsActivity {
                Divider().ignoresSafeArea()
                ActivityColumnView()
                    .environment(\.isSecondaryColumn, true)
                    .frame(maxWidth: 360)
            }
        }
    }
}

extension EnvironmentValues {
    @Entry var isSecondaryColumn = false
}
```

The column only appears in a regular horizontal size class and when the user
has left the toggle on. Choose the manual layout when you need full control or
a column the system split view has no slot for; choose `NavigationSplitView`
when the standard sidebar-content-detail shape fits with small tweaks.

## Sheets

- When a sheet shows a particular model, use `.sheet(item:)`; keep
  `.sheet(isPresented:)` for pure on/off states.
- A sheet owns its buttons and closes itself with `dismiss()`.
- `.presentationSizing(_:)` (iOS 18+) sets the size instead of fixed frames.

| `PresentationSizing` | Result |
| --- | --- |
| `.automatic` | Platform default |
| `.page` | Roughly paper-sized, for reading material |
| `.form` | Slightly narrower than `.page`, for data entry |
| `.fitted` | The content's ideal size |

`.fitted(horizontal:vertical:)` restricts fitting to the axes you pass, and
`.sticky(horizontal:vertical:)` lets a sheet grow along those axes but never
shrink back.

To stop a sheet with unsaved edits from being swiped away on iOS, use
`.interactiveDismissDisabled(hasEdits)` and confirm from your own Close button.
`.dismissalConfirmationDialog(_:shouldPresent:)` does this on macOS 15+ only;
the SDK marks it unavailable on iOS.

For larger apps, describe every modal as a case of an `Identifiable` enum held
on the router, and map the cases to views in one shared modifier. Any child can
then open a sheet by setting router state, with no bindings passed down. See
[references/sheets.md](references/sheets.md).

## Tabs

Use the `Tab` type with a typed selection, and give every tab its own
`NavigationStack`.

```swift
enum HomeTab: Hashable { case today, explore, compose, profile }

struct RootTabs: View {
    @State private var current: HomeTab = .today
    @State private var composing = false

    var body: some View {
        TabView(selection: Binding(get: { current }, set: select)) {
            Tab("Today", systemImage: "sun.max", value: .today) {
                NavigationStack { TodayView() }
            }
            Tab("Explore", systemImage: "map", value: .explore) {
                NavigationStack { ExploreView() }
            }
            Tab("New", systemImage: "plus.circle", value: .compose) {
                Color.clear
            }
            Tab("Me", systemImage: "person", value: .profile) {
                NavigationStack { ProfileView() }
            }
        }
        .sheet(isPresented: $composing) { ComposerView() }
    }

    private func select(_ next: HomeTab) {
        if next == .compose {
            composing = true
        } else {
            current = next
        }
    }
}
```

The custom binding sends every change through `select`, so a tab like
"New" can run an action instead of becoming the selected tab.

### Tab APIs from iOS 18 and iOS 26

From iOS 18 (macOS 15):

- `Tab(role: .search)` marks the search tab; the iOS 26 tab bar shows it as a
  search field while that tab is active.
- `.tabViewSidebarHeader { }` and `.tabViewSidebarFooter { }` customise the
  sidebar on iPadOS and macOS.
- `TabSection` collects tabs under a sidebar heading; mark it with
  `.tabPlacement(.sidebarOnly)` to keep it out of the compact bar.

From iOS 26 only:

- `.tabBarMinimizeBehavior(_:)` with `.onScrollDown`, `.onScrollUp` or `.never`.
  iPhone only.
- `.tabViewBottomAccessory { }` pins a view just above the tab bar, such as a
  mini player.

More in [references/tabview.md](references/tabview.md).

## Deep links

### Universal links

A universal link is an ordinary HTTPS URL that opens the app when installed.
It needs two things:

1. An `apple-app-site-association` file served from
   `/.well-known/apple-app-site-association` on the domain.
2. The Associated Domains entitlement listing `applinks:example.com`.

Handle both entry points on the root content of the `WindowGroup`:

```swift
@main
struct HikerApp: App {
    @State private var router = Router()

    var body: some Scene {
        WindowGroup {
            RootTabs()
                .environment(router)
                .onOpenURL { link in _ = router.handle(url: link) }
                .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
                    if let link = activity.webpageURL {
                        _ = router.handle(url: link)
                    }
                }
        }
    }
}
```

### Custom URL schemes

List the scheme under `CFBundleURLTypes` in Info.plist and handle it in
`.onOpenURL`. For links people share publicly, prefer universal links: they
have a web fallback and the domain is verified.

### Handoff

Publish the current activity with `.userActivity()` and pick it up with
`.onContinueUserActivity()`. Every activity type must appear in the Info.plist
`NSUserActivityTypes` array. Set `isEligibleForHandoff = true` and supply a
`webpageURL` for devices without the app.

Details, AASA format and scheme parsing: [references/deeplinks.md](references/deeplinks.md).

## Common mistakes

- Reaching for `NavigationView`. It is deprecated; use `NavigationStack` or
  `NavigationSplitView`.
- Letting every tab share one `NavigationPath`. Each tab keeps its own history.
- Driving a model-backed sheet with `.sheet(isPresented:)` instead of
  `.sheet(item:)`.
- Putting views in the path. The path holds small `Hashable` route values.
- Writing `NavigationStack(path: $router.path)` where `router` is a plain `let`
  or comes from `@Environment`. That gives no binding and does not compile;
  declare the property `@Bindable var router: Router`, or add
  `@Bindable var router = router` inside `body`.
- Building tabs with the older `.tabItem { }` instead of `Tab(value:)` with
  `TabView(selection:)`.
- Expecting `tabBarMinimizeBehavior` to do anything on iPad. It is iPhone only.
- Parsing URLs in several views. The router is the one place that parses them.
- Giving sheets fixed frame sizes instead of `.presentationSizing(.form)`.
- Leaving `@MainActor` off the router class, which Swift 6 concurrency checking
  needs.

## Review checklist

- [ ] `NavigationStack` everywhere, no `NavigationView`
- [ ] Each tab has its own `NavigationStack` and its own path
- [ ] The route enum is `Hashable` and its identifiers are stable
- [ ] `.navigationDestination(for:)` handles every route type that can be pushed
- [ ] `.sheet(item:)` is used for model-backed sheets
- [ ] Sheets handle their own dismissal
- [ ] The router is `@MainActor` and `@Observable`
- [ ] Incoming URLs are parsed and validated before any navigation happens
- [ ] Universal links have the AASA file and Associated Domains in place
- [ ] Tab selection uses `Tab(value:)` with a selection binding

## References

- [references/navigationstack.md](references/navigationstack.md): routers, per-tab stacks, centralised destinations, data-driven tabs
- [references/sheets.md](references/sheets.md): enum sheet routing, sizing, dismissal confirmation
- [references/tabview.md](references/tabview.md): tab architecture, custom selection binding, dynamic tabs, the iOS 18 and iOS 26 tab APIs
- [references/deeplinks.md](references/deeplinks.md): router URL handling, universal links and AASA, custom schemes, Handoff
