Swiftui Navigation

SwiftUI Navigation

Navigation patterns for SwiftUI apps targeting iOS 26+ with Swift 6.3. Covers push navigation, multi-column layouts, sheet presentation, tab architecture, and deep linking. Patterns are backward-compatible to iOS 17 unless noted.

Contents

• NavigationStack (Push Navigation)
• NavigationSplitView (Multi-Column)
• Sheet Presentation
• Tab-Based Navigation
• Deep Links
• Common Mistakes
• Review Checklist
• References

NavigationStack (Push Navigation)

Use NavigationStack with a NavigationPath binding for programmatic, type-safe push navigation. Define routes as a Hashable enum and map them with .navigationDestination(for:).

struct ContentView: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            List(items) { item in
                NavigationLink(value: item) {
                    ItemRow(item: item)
                }
            }
            .navigationDestination(for: Item.self) { item in
                DetailView(item: item)
            }
            .navigationTitle("Items")
        }
    }
}

Programmatic navigation:

path.append(item)        // Push
path.removeLast()        // Pop one
path = NavigationPath()  // Pop to root

Router pattern: For apps with complex navigation, use a router object that owns the path and sheet state. Each tab gets its own router instance injected via .environment(). Centralize destination mapping with a single .navigationDestination(for:) block or a shared withAppRouter() modifier.

See references/navigationstack.md for full router examples including per-tab stacks, centralized destination mapping, and generic tab routing.

NavigationSplitView (Multi-Column)

Use NavigationSplitView for sidebar-detail layouts on iPad and Mac. Falls back to stack navigation on iPhone.

struct MasterDetailView: View {
    @State private var selectedItem: Item?

    var body: some View {
        NavigationSplitView {
            List(items, selection: $selectedItem) { item in
                NavigationLink(value: item) { ItemRow(item: item) }
            }
            .navigationTitle("Items")
        } detail: {
            if let item = selectedItem {
                ItemDetailView(item: item)
            } else {
                ContentUnavailableView("Select an Item", systemImage: "sidebar.leading")
            }
        }
    }
}

Custom Split Column (Manual HStack)

For custom multi-column layouts (e.g., a dedicated notification column independent of selection), use a manual HStack split with horizontalSizeClass checks:

@MainActor
struct AppView: View {
  @Environment(\.horizontalSizeClass) private var horizontalSizeClass
  @AppStorage("showSecondaryColumn") private var showSecondaryColumn = true

  var body: some View {
    HStack(spacing: 0) {
      primaryColumn
      if shouldShowSecondaryColumn {
        Divider().edgesIgnoringSafeArea(.all)
        secondaryColumn
      }
    }
  }

  private var shouldShowSecondaryColumn: Bool {
    horizontalSizeClass == .regular
      && showSecondaryColumn
  }

  private var primaryColumn: some View {
    TabView { /* tabs */ }
  }

  private var secondaryColumn: some View {
    NotificationsTab()
      .environment(\.isSecondaryColumn, true)
      .frame(maxWidth: .secondaryColumnWidth)
  }
}

Use the manual HStack split when you need full control or a non-standard secondary column. Use NavigationSplitView when you want a standard system layout with minimal customization.

Sheet Presentation

Prefer .sheet(item:) over .sheet(isPresented:) when state represents a selected model. Sheets should own their actions and call dismiss() internally.

@State private var selectedItem: Item?

.sheet(item: $selectedItem) { item in
    EditItemSheet(item: item)
}

Presentation sizing (iOS 18+): Control sheet dimensions with .presentationSizing:

.sheet(item: $selectedItem) { item in
    EditItemSheet(item: item)
        .presentationSizing(.form)  // .form, .page, .fitted, .automatic
}

PresentationSizing values:

• .automatic -- platform default
• .page -- roughly paper size, for informational content
• .form -- slightly narrower than page, for form-style UI
• .fitted -- sized by the content's ideal size

Fine-tuning: .fitted(horizontal:vertical:) constrains fitting axes; .sticky(horizontal:vertical:) grows but does not shrink in specified dimensions.

Dismissal confirmation (macOS 15+ / iOS 26+): Use .dismissalConfirmationDialog("Discard?", shouldPresent: hasUnsavedChanges) to prevent accidental dismissal of sheets with unsaved changes.

Enum-driven sheet routing: Define a SheetDestination enum that is Identifiable, store it on the router, and map it with a shared view modifier. This lets any child view present sheets without prop-drilling. See references/sheets.md for the full centralized sheet routing pattern.

Tab-Based Navigation

Use the Tab API with a selection binding for scalable tab architecture. Each tab should wrap its content in an independent NavigationStack.

struct MainTabView: View {
    @State private var selectedTab: AppTab = .home

    var body: some View {
        TabView(selection: $selectedTab) {
            Tab("Home", systemImage: "house", value: .home) {
                NavigationStack { HomeView() }
            }
            Tab("Search", systemImage: "magnifyingglass", value: .search) {
                NavigationStack { SearchView() }
            }
            Tab("Profile", systemImage: "person", value: .profile) {
                NavigationStack { ProfileView() }
            }
        }
    }
}

Custom binding with side effects: Route selection changes through a function to intercept special tabs (e.g., compose) that should trigger an action instead of changing selection.

iOS 26 Tab Additions

• `Tab(role: .search)` -- replaces the tab bar with a search field when active
• `.tabBarMinimizeBehavior(_:)` -- .onScrollDown, .onScrollUp, .never (iPhone only)
• `.tabViewSidebarHeader/Footer` -- customize sidebar sections on iPadOS/macOS
• `.tabViewBottomAccessory { }` -- attach content below the tab bar (e.g., Now Playing bar)
• `TabSection` -- group tabs into sidebar sections with .tabPlacement(.sidebarOnly)

See references/tabview.md for full TabView patterns including custom bindings, dynamic tabs, and sidebar customization.

Deep Links

Universal Links

Universal links let iOS open your app for standard HTTPS URLs. They require: 1. An Apple App Site Association (AASA) file at /.well-known/apple-app-site-association 2. An Associated Domains entitlement (applinks:example.com)

Handle in SwiftUI with .onOpenURL and .onContinueUserActivity:

@main
struct MyApp: App {
    @State private var router = Router()

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(router)
                .onOpenURL { url in router.handle(url: url) }
                .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
                    guard let url = activity.webpageURL else { return }
                    router.handle(url: url)
                }
        }
    }
}

Custom URL Schemes

Register schemes in Info.plist under CFBundleURLTypes. Handle with .onOpenURL. Prefer universal links over custom schemes for publicly shared links -- they provide web fallback and domain verification.

Handoff (NSUserActivity)

Advertise activities with .userActivity() and receive them with .onContinueUserActivity(). Declare activity types in Info.plist under NSUserActivityTypes. Set isEligibleForHandoff = true and provide a webpageURL as fallback.

See references/deeplinks.md for full examples of AASA configuration, router URL handling, custom URL schemes, and NSUserActivity continuation.

Common Mistakes

1. Using deprecated NavigationView -- use NavigationStack or NavigationSplitView 2. Sharing one NavigationPath across all tabs -- each tab needs its own path 3. Using .sheet(isPresented:) when state represents a model -- use .sheet(item:) instead 4. Storing view instances in NavigationPath -- store lightweight Hashable route data 5. Nesting @Observable router objects inside other @Observable objects 6. Prefer Tab(value:) with TabView(selection:) over the older .tabItem { } API 7. Assuming tabBarMinimizeBehavior works on iPad -- it is iPhone only 8. Handling deep links in multiple places -- centralize URL parsing in the router 9. Hard-coding sheet frame dimensions -- use .presentationSizing(.form) instead 10. Missing @MainActor on router classes -- required for Swift 6 concurrency safety

Review Checklist

• [ ] NavigationStack used (not NavigationView)
• [ ] Each tab has its own NavigationStack with independent path
• [ ] Route enum is Hashable with stable identifiers
• [ ] .navigationDestination(for:) maps all route types
• [ ] .sheet(item:) preferred over .sheet(isPresented:)
• [ ] Sheets own their dismiss logic internally
• [ ] Router object is @MainActor and @Observable
• [ ] Deep link URLs parsed and validated before navigation
• [ ] Universal links have AASA and Associated Domains configured
• [ ] Tab selection uses Tab(value:) with binding

References

• NavigationStack and router patterns: references/navigationstack.md
• Sheet presentation and routing: references/sheets.md
• TabView patterns and iOS 26 API: references/tabview.md
• Deep links, universal links, and Handoff: references/deeplinks.md
• Architecture and state management: see swiftui-patterns skill
• Layout and components: see swiftui-layout-components skill

Deep links and navigation

Contents

• Intent
• Core patterns
• Example: router entry points
• Example: attach to a root view
• Design choices to keep
• Pitfalls
• Universal Links
• Custom URL Schemes
• NSUserActivity Continuation (Handoff)

Intent

Route external URLs into in-app destinations while falling back to system handling when needed.

Core patterns

• Centralize URL handling in the router (handle(url:), handleDeepLink(url:)).
• Inject an OpenURLAction handler that delegates to the router.
• Use .onOpenURL for app scheme links and convert them to web URLs if needed.
• Let the router decide whether to navigate or open externally.

Example: router entry points

@MainActor
final class RouterPath {
  var path: [Route] = []
  var urlHandler: ((URL) -> OpenURLAction.Result)?

  func handle(url: URL) -> OpenURLAction.Result {
    if isInternal(url) {
      navigate(to: .status(id: url.lastPathComponent))
      return .handled
    }
    return urlHandler?(url) ?? .systemAction
  }

  func handleDeepLink(url: URL) -> OpenURLAction.Result {
    // Resolve federated URLs, then navigate.
    navigate(to: .status(id: url.lastPathComponent))
    return .handled
  }
}

Example: attach to a root view

extension View {
  func withLinkRouter(_ router: RouterPath) -> some View {
    self
      .environment(
        \.openURL,
        OpenURLAction { url in
          router.handle(url: url)
        }
      )
      .onOpenURL { url in
        router.handleDeepLink(url: url)
      }
  }
}

Design choices to keep

• Keep URL parsing and decision logic inside the router.
• Avoid handling deep links in multiple places; one entry point is enough.
• Always provide a fallback to @Environment(\.openURL) via OpenURLAction.

Pitfalls

• Don’t assume the URL is internal; validate first.
• Avoid blocking UI while resolving remote links; use Task.

Universal Links

Universal links let iOS open your app when a user taps a standard HTTPS URL, with no custom scheme required. They require server-side configuration and an Associated Domains entitlement.

Apple App Site Association (AASA)

Host a JSON file at https://example.com/.well-known/apple-app-site-association (no file extension, served with Content-Type: application/json):

{
  "applinks": {
    "details": [
      {
        "appIDs": ["TEAMID.com.example.app"],
        "components": [
          { "/": "/items/*", "comment": "Match item detail paths" },
          { "/": "/profile/*" }
        ]
      }
    ]
  }
}

Key rules:

• AASA must be served over HTTPS with a valid certificate — no redirects.
• Apple's CDN caches the file; updates can take 24-48 hours. Use https://app-site-association.cdn-apple.com/a/v1/example.com to verify the cached version.
• Use components (modern) over the legacy paths array.

Associated Domains entitlement

In your app's .entitlements file (or Signing & Capabilities in Xcode), add:

com.apple.developer.associated-domains = [
    "applinks:example.com",
    "applinks:www.example.com"
]

For development/testing, prefix with applinks:example.com?mode=developer to bypass the CDN cache.

Handling Universal Links in SwiftUI

Use .onOpenURL for link-based launches and onContinueUserActivity for NSUserActivity-based handoff:

@main
struct MyApp: App {
    @State private var router = Router()

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(router)
                .onOpenURL { url in
                    router.handle(url: url)
                }
                .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
                    guard let url = activity.webpageURL else { return }
                    router.handle(url: url)
                }
        }
    }
}

Docs: Supporting universal links

Custom URL Schemes

Custom URL schemes (e.g., myapp://) let other apps or websites open your app. They do not require server configuration but offer no fallback if the app is not installed.

Registering in Info.plist

Add CFBundleURLTypes to your target's Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
    <key>CFBundleURLName</key>
    <string>com.example.myapp</string>
  </dict>
</array>

Handling with .onOpenURL

.onOpenURL { url in
    // url.scheme == "myapp"
    // url.host == "items", url.pathComponents for routing
    guard url.scheme == "myapp" else { return }
    router.handle(url: url)
}

Prefer universal links over custom schemes for publicly shared links — they provide a better UX (web fallback) and are more secure (domain-verified).

NSUserActivity Continuation (Handoff)

Handoff lets users start an activity on one device and continue it on another. SwiftUI provides .onContinueUserActivity and .userActivity modifiers.

Advertising an activity

struct ItemDetailView: View {
    let item: Item

    var body: some View {
        ScrollView { /* content */ }
            .userActivity("com.example.viewItem") { activity in
                activity.title = item.title
                activity.isEligibleForHandoff = true
                activity.isEligibleForSearch = true
                activity.targetContentIdentifier = item.id.uuidString
                activity.webpageURL = URL(string: "https://example.com/items/\(item.id)")
            }
    }
}

Receiving a continued activity

.onContinueUserActivity("com.example.viewItem") { activity in
    guard let id = activity.targetContentIdentifier else { return }
    router.navigate(to: .item(id: id))
}

Key rules:

• Activity types must be declared in Info.plist under NSUserActivityTypes.
• Set isEligibleForHandoff = true and optionally isEligibleForSearch / isEligibleForPrediction.
• Provide a webpageURL as fallback when the app is not installed on the receiving device.

NavigationStack

Contents

• Intent
• Core architecture
• Example: custom router with per-tab stack
• Example: centralized destination mapping
• Example: binding per tab (tabs with independent history)
• Example: generic tabs with per-tab NavigationStack
• Design choices to keep
• Pitfalls

Intent

Use this pattern for programmatic navigation and deep links, especially when each tab needs an independent navigation history. The key idea is one NavigationStack per tab, each with its own path binding and router object.

Core architecture

• Define a route enum that is Hashable and represents all destinations.
• Create a lightweight router (or use a library such as https://github.com/Dimillian/AppRouter) that owns the path and any sheet state.
• Each tab owns its own router instance and binds NavigationStack(path:) to it.
• Inject the router into the environment so child views can navigate programmatically.
• Centralize destination mapping with a single navigationDestination(for:) block (or a withAppRouter() modifier).

Example: custom router with per-tab stack

@MainActor
@Observable
final class RouterPath {
  var path: [Route] = []
  var presentedSheet: SheetDestination?

  func navigate(to route: Route) {
    path.append(route)
  }

  func reset() {
    path = []
  }
}

enum Route: Hashable {
  case account(id: String)
  case status(id: String)
}

@MainActor
struct TimelineTab: View {
  @State private var routerPath = RouterPath()

  var body: some View {
    NavigationStack(path: $routerPath.path) {
      TimelineView()
        .navigationDestination(for: Route.self) { route in
          switch route {
          case .account(let id): AccountView(id: id)
          case .status(let id): StatusView(id: id)
          }
        }
    }
    .environment(routerPath)
  }
}

Example: centralized destination mapping

Use a shared view modifier to avoid duplicating route switches across screens.

extension View {
  func withAppRouter() -> some View {
    navigationDestination(for: Route.self) { route in
      switch route {
      case .account(let id):
        AccountView(id: id)
      case .status(let id):
        StatusView(id: id)
      }
    }
  }
}

Then apply it once per stack:

NavigationStack(path: $routerPath.path) {
  TimelineView()
    .withAppRouter()
}

Example: binding per tab (tabs with independent history)

@MainActor
struct TabsView: View {
  @State private var selectedTab: AppTab = .timeline
  @State private var timelineRouter = RouterPath()
  @State private var notificationsRouter = RouterPath()

  var body: some View {
    TabView(selection: $selectedTab) {
      Tab("Timeline", systemImage: "text.bubble", value: .timeline) {
        TimelineTab(router: timelineRouter)
      }
      Tab("Notifications", systemImage: "bell", value: .notifications) {
        NotificationsTab(router: notificationsRouter)
      }
    }
  }
}

Example: generic tabs with per-tab NavigationStack

Use this when tabs are built from data and each needs its own path without hard-coded names.

@MainActor
struct TabsView: View {
  @State private var selectedTab: AppTab = .timeline
  @State private var tabRouter = TabRouter()

  var body: some View {
    TabView(selection: $selectedTab) {
      ForEach(AppTab.allCases) { tab in
        Tab(value: tab) {
          NavigationStack(path: tabRouter.binding(for: tab)) {
            tab.makeContentView()
          }
          .environment(tabRouter.router(for: tab))
        } label: {
          tab.label
        }
      }
    }
  }
}

@MainActor @Observable final class TabRouter { private var routers: [AppTab: RouterPath] = [:]

func router(for tab: AppTab) -> RouterPath { if let router = routers[tab] { return router } let router = RouterPath() routers[tab] = router return router }

func binding(for tab: AppTab) -> Binding<[Route]> { let router = router(for: tab) return Binding(get: { router.path }, set: { router.path = $0 }) } }

Design choices to keep

• One NavigationStack per tab to preserve independent history.
• A single source of truth for navigation state (RouterPath or library router).
• Use navigationDestination(for:) to map routes to views.
• Reset the path when app context changes (account switch, logout, etc.).
• Inject the router into the environment so child views can navigate and present sheets without prop-drilling.
• Keep sheet presentation state on the router if you want a single place to manage modals.

Pitfalls

• Do not share one path across all tabs unless you want global history.
• Ensure route identifiers are stable and Hashable.
• Avoid storing view instances in the path; store lightweight route data instead.
• If using a router object, keep it outside other @Observable objects to avoid nested observation.

Sheets

Contents

• Intent
• Core architecture
• Example: SheetDestination enum
• Example: withSheetDestinations modifier
• Example: presenting from a child view
• Required wiring
• Example: sheets that need their own navigation
• Design choices to keep
• iOS 26 Presentation Sizing
• Pitfalls

Intent

Use a centralized sheet routing pattern so any view can present modals without prop-drilling. This keeps sheet state in one place and scales as the app grows.

Core architecture

• Define a SheetDestination enum that describes every modal and is Identifiable.
• Store the current sheet in a router object (presentedSheet: SheetDestination?).
• Create a view modifier like withSheetDestinations(...) that maps the enum to concrete sheet views.
• Inject the router into the environment so child views can set presentedSheet directly.

Example: SheetDestination enum

enum SheetDestination: Identifiable, Hashable {
  case composer
  case editProfile
  case settings
  case report(itemID: String)

  var id: String {
    switch self {
    case .composer, .editProfile:
      // Use the same id to ensure only one editor-like sheet is active at a time.
      return "editor"
    case .settings:
      return "settings"
    case .report:
      return "report"
    }
  }
}

Example: withSheetDestinations modifier

extension View {
  func withSheetDestinations(
    sheet: Binding<SheetDestination?>
  ) -> some View {
    sheet(item: sheet) { destination in
      Group {
        switch destination {
        case .composer:
          ComposerView()
        case .editProfile:
          EditProfileView()
        case .settings:
          SettingsView()
        case .report(let itemID):
          ReportView(itemID: itemID)
        }
      }
    }
  }
}

Example: presenting from a child view

struct StatusRow: View {
  @Environment(RouterPath.self) private var router

  var body: some View {
    Button("Report") {
      router.presentedSheet = .report(itemID: "123")
    }
  }
}

Required wiring

For the child view to work, a parent view must:

• own the router instance,
• attach withSheetDestinations(sheet: $router.presentedSheet) (or an equivalent sheet(item:) handler), and
• inject it with .environment(router) after the sheet modifier so the modal content inherits it.

This makes the child assignment to router.presentedSheet drive presentation at the root.

Example: sheets that need their own navigation

Wrap sheet content in a NavigationStack so it can push within the modal.

struct NavigationSheet<Content: View>: View {
  var content: () -> Content

  var body: some View {
    NavigationStack {
      content()
        .toolbar { CloseToolbarItem() }
    }
  }
}

Design choices to keep

• Centralize sheet routing so features can present modals without wiring bindings through many layers.
• Use sheet(item:) to guarantee a single sheet is active and to drive presentation from the enum.
• Group related sheets under the same id when they are mutually exclusive (e.g., editor flows).
• Keep sheet views lightweight and composed from smaller views; avoid large monoliths.

iOS 26 Presentation Sizing

Control sheet dimensions with presentationSizing(_:) (iOS 18+):

.sheet(item: $selectedItem) { item in
    EditItemSheet(item: item)
        .presentationSizing(.form)
}

PresentationSizing values:

• .automatic -- platform default
• .page -- roughly paper size, for informational content
• .form -- slightly narrower than page, for form-style UI
• .fitted -- sized by the content's ideal size

Modifier methods for fine-tuning:

• .fitted(horizontal:vertical:) -- constrain fitting to specific axes
• .sticky(horizontal:vertical:) -- grow but do not shrink in specified dimensions

Dismissal Confirmation (macOS 15+ / iOS 26+)

Show a confirmation dialog when the user tries to dismiss a sheet with unsaved changes:

.sheet(item: $selectedItem) { item in
    EditItemSheet(item: item)
        .dismissalConfirmationDialog(
            "Discard changes?",
            shouldPresent: hasUnsavedChanges
        ) {
            Button("Discard", role: .destructive) { discardChanges() }
        }
}

• Cancel action is included automatically and prevents dismissal
• All other action buttons allow dismissal to proceed
• Use .keyboardShortcut(.defaultAction) to set the default button

Pitfalls

• Avoid mixing sheet(isPresented:) and sheet(item:) for the same concern; prefer a single enum.
• Do not store heavy state inside SheetDestination; pass lightweight identifiers or models.
• If multiple sheets can appear from the same screen, give them distinct id values.
• Use presentationSizing(.form) for form sheets instead of hard-coding frame dimensions.
• Always pair dismissalConfirmationDialog with a shouldPresent condition; showing it when there are no changes is confusing.

TabView

Contents

• Intent
• Core architecture
• Example: custom binding with side effects
• Example: direct binding without side effects
• Design choices to keep
• Dynamic tabs pattern
• iOS 26 Tab API
• Pitfalls

Intent

Use this pattern for a scalable, multi-platform tab architecture with:

• a single source of truth for tab identity and content,
• platform-specific tab sets and sidebar sections,
• dynamic tabs sourced from data,
• an interception hook for special tabs (e.g., compose).

Core architecture

• AppTab enum defines identity, labels, icons, and content builder.
• SidebarSections enum groups tabs for sidebar sections.
• AppView owns the TabView and selection binding, and routes tab changes through updateTab.

Example: custom binding with side effects

Use this when tab selection needs side effects, like intercepting a special tab to perform an action instead of changing selection.

@MainActor
struct AppView: View {
  @Binding var selectedTab: AppTab

  var body: some View {
    TabView(selection: .init(
      get: { selectedTab },
      set: { updateTab(with: $0) }
    )) {
      ForEach(availableSections) { section in
        TabSection(section.title) {
          ForEach(section.tabs) { tab in
            Tab(value: tab) {
              tab.makeContentView(
                homeTimeline: $timeline,
                selectedTab: $selectedTab,
                pinnedFilters: $pinnedFilters
              )
            } label: {
              tab.label
            }
            .tabPlacement(tab.tabPlacement)
          }
        }
        .tabPlacement(.sidebarOnly)
      }
    }
  }

  private func updateTab(with newTab: AppTab) {
    if newTab == .post {
      // Intercept special tabs (compose) instead of changing selection.
      presentComposer()
      return
    }
    selectedTab = newTab
  }
}

Example: direct binding without side effects

Use this when selection is purely state-driven.

@MainActor
struct AppView: View {
  @Binding var selectedTab: AppTab

  var body: some View {
    TabView(selection: $selectedTab) {
      ForEach(availableSections) { section in
        TabSection(section.title) {
          ForEach(section.tabs) { tab in
            Tab(value: tab) {
              tab.makeContentView(
                homeTimeline: $timeline,
                selectedTab: $selectedTab,
                pinnedFilters: $pinnedFilters
              )
            } label: {
              tab.label
            }
            .tabPlacement(tab.tabPlacement)
          }
        }
        .tabPlacement(.sidebarOnly)
      }
    }
  }
}

Design choices to keep

• Centralize tab identity and content in AppTab with makeContentView(...).
• Use Tab(value:) with selection binding for state-driven tab selection.
• Route selection changes through updateTab to handle special tabs and scroll-to-top behavior.
• Use TabSection + .tabPlacement(.sidebarOnly) for sidebar structure.
• Use .tabPlacement(.pinned) in AppTab.tabPlacement for a single pinned tab; this is commonly used for iOS 26 .searchable tab content, but can be used for any tab.

Dynamic tabs pattern

• SidebarSections handles dynamic data tabs.
• AppTab.anyTimelineFilter(filter:) wraps dynamic tabs in a single enum case.
• The enum provides label/icon/title for dynamic tabs via the filter type.

iOS 26 Tab API

iOS 26 expands the Tab API with minimize behavior, roles, and accessory placements.

Tab Bar Minimization

TabView(selection: $selectedTab) {
    // tabs
}
.tabBarMinimizeBehavior(.onScrollDown) // iPhone only

TabBarMinimizeBehavior values:

• .automatic -- determine behavior from context
• .onScrollDown -- minimize when user scrolls down (iPhone only)
• .onScrollUp -- minimize when user scrolls up (iPhone only)
• .never -- never minimize the tab bar

Tab Search Role

Replace the tab bar with a search field when the search tab is active:

Tab(role: .search) {
    SearchView()
}

Sidebar Customization

TabView {
    // tabs
}
.tabViewSidebarHeader { SidebarHeaderView() }
.tabViewSidebarFooter { SidebarFooterView() }
.tabViewSidebarBottomBar { BottomBarView() }

Bottom Accessory

Use TabViewBottomAccessoryPlacement for content below the tab bar:

TabView {
    // tabs
}
.tabViewBottomAccessory { NowPlayingBar() }

Pitfalls

• Avoid adding ViewModels for tabs; keep state local or in @Observable services.
• Do not nest @Observable objects inside other @Observable objects.
• Ensure AppTab.id values are stable; dynamic cases should hash on stable IDs.
• Special tabs (compose) should not change selection.
• Prefer Tab(value:) with TabView(selection:) over the older .tabItem { } API for typed tab selection.
• tabBarMinimizeBehavior only works on iPhone; it has no effect on iPad or Mac.