skip to content

In SwiftUI, what does TabView's sidebarAdaptable style do on iPad and iPhone, and when would you choose it over NavigationSplitView?

level: middleimportance: should knowfreq 30%

answer

  1. a tab bar that can become a sidebar
  2. secondary tabs grouped under a header
  3. flattened into the bar on iPhone
  4. people rearrange and hide tabs
  5. destinations versus drill-down

basics

~20 s

The sidebarAdaptable TabView style, from iOS 18, lets iPad people switch between a tab bar and a sidebar that shows TabSection groups, while iPhone keeps a tab bar. Choose it for top-level destinations; choose NavigationSplitView for list-to-detail drilling.

solid answer

~40 s

`.tabViewStyle(.sidebarAdaptable)` (iOS 18) turns a `TabView` into one model for both devices. On iPadOS people can toggle between the tab bar and a sidebar; `TabSection` groups secondary tabs under a header and appears in both. On iPhone, and in the iPadOS compact size class, the secondary tabs show in the tab bar without the section header, so Apple advises keeping the count small. With `tabViewCustomization(_:)`, a `TabViewCustomization` stored in `@AppStorage` and a `customizationID(_:)` on each tab, people can drag, hide and reorder tabs. I choose it when the app is a set of **destinations** (Inbox, Flagged, each mailbox); I choose `NavigationSplitView` when the job is **drilling** from a list to a detail beside it.

code

swift · 39 lines
swift
struct Mailbox: Identifiable {
    let id: String
    let name: String
    let symbol: String
}

enum MailTab: Hashable {
    case inbox, flagged, search
    case mailbox(String)
}

struct MailAdaptableTabs: View {
    let mailboxes: [Mailbox]
    @State private var selection: MailTab = .inbox
    @AppStorage("mailTabCustomization")
    private var customization: TabViewCustomization

    var body: some View {
        TabView(selection: $selection) {
            Tab("Inbox", systemImage: "tray", value: MailTab.inbox) { InboxView() }
                .customizationID("mail.inbox")
            Tab("Flagged", systemImage: "flag", value: MailTab.flagged) { FlaggedView() }
                .customizationID("mail.flagged")
            Tab(value: MailTab.search, role: .search) { MailSearchView() }

            TabSection("Mailboxes") {
                ForEach(mailboxes) { box in
                    Tab(box.name, systemImage: box.symbol, value: MailTab.mailbox(box.id)) {
                        MailboxView(mailboxID: box.id)
                    }
                    .customizationID("mail.box.\(box.id)")
                }
            }
            .customizationID("mail.mailboxes")
        }
        .tabViewStyle(.sidebarAdaptable)
        .tabViewCustomization($customization)
    }
}

go deeper

for a junior

Recall that sidebarAdaptable is a TabView style from iOS 18 that can show the same tabs as a sidebar on iPad.

for a middle

Explain how TabSection, the compact tab bar, defaultVisibility and customization IDs behave across iPad and iPhone.

for a senior

Show when a destination-style sidebar beats a split view, and how to persist customization without breaking it on later releases.

for a principal

Decide which sections are fixed, which are customizable, and when the iOS 18 minimum is worth adopting for this structure.

## What the style is `TabView` takes a style through `tabViewStyle(_:)`. In iOS 18 Apple added `sidebarAdaptable` (the `SidebarAdaptableTabViewStyle` type), together with `Tab`, `TabSection` and tab customization. Apple's sample describes it as a style that "optimizes the content browsing experience for each platform": the same tab declarations become a tab bar where space is tight and a sidebar where there is room. ## How it looks on each device - **iPadOS, regular width:** from iPadOS 18 the tab bar floats at the top of the screen, and people can toggle between that tab bar and a **sidebar**. `TabSection` groups "appear in both the sidebar and the tab bar". - **iPhone, and iPadOS in the compact size class:** "secondary tabs appear in the tab bar", and "the section header doesn't appear in the tab bar". The documentation advises limiting the number of tabs there "so all tabs fit in the tab bar". - **Other styles:** `.tabBarOnly` (iOS 18) keeps the tab-bar presentation only; `.grouped` is a macOS-only style and is unavailable on iOS. ## Building the hierarchy 1. Declare top-level tabs with `Tab`, each with a `value:` if you need programmatic selection. 2. Group secondary tabs in a `TabSection("Mailboxes") { ... }`; a `ForEach` inside it can create one tab per user mailbox. 3. Apply `.tabViewStyle(.sidebarAdaptable)` to the `TabView`. 4. Use `defaultVisibility(.hidden, for: .tabBar)` on a section to keep its tabs in the sidebar by default while still letting people drag one into the tab bar, or the `sidebarOnly` tab placement to keep a tab out of the tab bar altogether. Apple's `TabView` page also shows a heavier pattern: a "Browse" tab hidden in the regular size class and the sections hidden in compact, with an `onChange(of:initial:_:)` that maps the selection across when the size class changes. It works, but it is a lot of state to keep consistent and earns its place only when the compact tab set must differ. ## Letting people customise `tabViewCustomization(_:)` takes a binding to a `TabViewCustomization`. People can then drag tabs between the sidebar and the tab bar, hide tabs, and reorder them. Requirements: - every customizable `Tab` and `TabSection` needs a stable `customizationID(_:)`; - `customizationBehavior(.disabled, for: .sidebar, .tabBar)` pins a tab that must not move; - the value is `Codable`, and Apple's examples persist it with `@AppStorage` (or `@SceneStorage`). ## Selection, search and headers inside sections Everything from a plain tab view still applies inside the adaptive style: - `TabView(selection:)` with an enum works across sections; an enum case with an associated value, such as `case mailbox(String)`, covers tabs generated by `ForEach`. - A tab with the `.search` role keeps its default title and symbol and is pinned in the tab bar. - `TabSection` takes a header, either a string as in `TabSection("Mailboxes")` or a custom view through `init(content:header:)`; Apple's Destination Video sample uses a `Label` with a folder symbol. - On iPadOS, Apple's sample notes that when there are too many tabs to fit, "the system collapses the tabs that don't fit and enables scrolling", one more reason to keep the tab-bar set small. ## Choosing between it and NavigationSplitView | Question | `sidebarAdaptable` TabView | `NavigationSplitView` | |---|---|---| | What the sidebar lists | destinations, each a whole section | items whose detail appears beside them | | What selection does | swaps the whole content area | fills the next column | | On iPhone | a tab bar | a collapsed stack | | Minimum release | iOS 18 | iOS 16 | A mail app can use both: a `sidebarAdaptable` tab view for Inbox, Flagged, Search and the mailbox sections, and inside a mailbox's tab a list-to-reading-pane split. Which wins depends on whether people mostly **jump between areas** or **work through a list**. ## Common mistakes - Treating `sidebarAdaptable` as available on iOS 17. - Expecting section headers to show in the iPhone tab bar. - Omitting `customizationID(_:)` on tabs meant to be customizable; the documentation requires an ID on every customizable tab and section. - Putting a dozen secondary tabs in sections and expecting them all to fit on a phone. - Forcing a list-detail workflow into tabs, where each tap swaps the whole screen.

  • How do you keep a section's tabs out of the iPhone tab bar but still let iPad people pin one there?
    Apply `defaultVisibility(.hidden, for: .tabBar)` to the `TabSection`. The tabs start hidden from the tab bar and live in the sidebar, but with customization enabled people can still drag one into the tab bar. If a tab must never appear in the tab bar, use the `sidebarOnly` tab placement instead of a default visibility.
  • What do you need so tab customizations survive relaunch?
    A `TabViewCustomization` value bound with `tabViewCustomization(_:)`, persisted through `@AppStorage` (or `@SceneStorage` for per-scene state), plus a stable `customizationID(_:)` on every customizable tab and section. Changing an ID later means the stored customization no longer matches that tab.

  • Using the sidebarAdaptable style in an app that still deploys to iOS 17
  • Expecting TabSection headers to appear in the iPhone tab bar
  • Leaving customizationID off tabs that people are meant to customise
  • Using .grouped as the adaptive style on iOS
  • Forcing a list-to-detail workflow into tabs instead of a split view

Assumes the iOS 27 SDK; the sidebarAdaptable style, TabSection and tab customization were added in iOS 18.