skip to content

In SwiftUI, how do you switch tabs programmatically with TabView(selection:) and Tab values, and what does the search tab role add?

level: middleimportance: should knowfreq 50%

answer

  1. a binding the tab bar writes back
  2. one Hashable type for every tab
  3. unique value per tab
  4. set the state, the tab bar follows
  5. search role: defaults and pinning

basics

~20 s

Bind TabView(selection:) to @State and give every Tab a unique value of that Hashable type; assigning the state switches tabs. The iOS 18 search role adds Search's default title and symbol and pins the tab at the trailing edge.

solid answer

~40 s

I model the tabs as a `Hashable` enum, hold the current one in `@State`, and pass `$selection` to `TabView(selection:)`. Each `Tab` gets `value:` with a unique case of that enum; when someone taps a tab, SwiftUI writes its value into the binding, and when my code assigns a new value, the tab bar follows. So a Compose button in Inbox can switch to Drafts with `selection = .drafts`. `Tab(value: .search, role: .search)` (iOS 18) gets the default "Search" title and magnifying-glass symbol and is pinned at the trailing edge of the tab bar; on iOS 26 selecting it brings a search field in place of the tab bar. iOS 27 adds a `prominent` role that sets a tab apart in its own trailing position.

code

swift · 23 lines
swift
enum MailTab: Hashable {
    case inbox, sent, drafts, archive, search
}

struct MailTabs: View {
    @State private var selection: MailTab = .inbox
    let unreadCount: Int

    var body: some View {
        TabView(selection: $selection) {
            Tab("Inbox", systemImage: "tray", value: .inbox) {
                InboxView(onCompose: { selection = .drafts })
            }
            .badge(unreadCount)

            Tab("Sent", systemImage: "paperplane", value: .sent) { SentView() }
            Tab("Drafts", systemImage: "doc", value: .drafts) { DraftsView() }
            Tab("Archive", systemImage: "archivebox", value: .archive) { ArchiveView() }

            Tab(value: .search, role: .search) { MailSearchView() }
        }
    }
}

go deeper

for a junior

Remember the pattern: @State selection, TabView(selection:), and a value: on every Tab.

for a middle

Explain the two-way binding, why every tab needs a unique value of one Hashable type, and what the search role's defaults are.

for a senior

Show where the selection should live so actions in one tab can switch to another, and how dynamic tabs use enum associated values.

for a principal

Weigh which tabs earn a fixed place versus a role or a section, keeping the tab set small enough to fit the phone's tab bar.

## Selection as state `TabView` can run without a selection binding: the person taps tabs and SwiftUI remembers which one is showing. As soon as your code needs to **know** or **change** the current tab, you hand it a binding with `TabView(selection:)`. The binding is the single source of truth for the current tab, in both directions: - when someone taps a tab, the tab view "updates the selection binding to the value of the currently selected tab" (Apple's `TabView` documentation); - when your code assigns a new value to the bound state, the tab view shows the matching tab. ## Giving tabs values Since iOS 18 each `Tab` takes a `value:` argument. Apple's documentation states two rules: "Each tab should have a unique selection value and all tabs should have the same selection value type." In practice that means: 1. Define a `Hashable` type, usually an enum: `enum MailTab: Hashable { case inbox, sent, drafts, archive, search }`. 2. Hold it in `@State private var selection: MailTab = .inbox` in the view that owns the `TabView`. 3. Write `TabView(selection: $selection)` and give every `Tab` a distinct case with `value:`. An enum keeps the set closed, makes `switch` exhaustive and lets cases carry associated values for dynamic tabs, such as `case mailbox(Mailbox.ID)` for one tab per mailbox. Before iOS 18 the same job was done with `.tag(_:)` on each child view and `TabView(selection:content:)`; the tag's type had to match the binding's type for the selection to resolve. The iOS 27 SDK marks that view-builder initializer for future deprecation in favour of the `TabContentBuilder` ones. ## Switching programmatically Because selection is ordinary state, any code that can reach the binding can change tabs: - a Compose button in Inbox calls a closure that sets `selection = .drafts`; - a model object that owns the selection can switch tabs after a background save; - a value restored at launch can reopen the tab someone last used. Pass a closure or a `Binding` down to the child that needs to switch, rather than letting children reach for a global. Turning an incoming URL into a tab plus a navigation path, and popping a tab's stack to its root when its tab is selected again, belong to the lesson on stack-based routing; the tab half is just this assignment. ## Worked example: a five-tab mail app On iPhone the mail app has five tabs: Inbox, Sent, Drafts, Archive and Search. The enum `MailTab` has one case per tab, and the root view owns `@State private var selection: MailTab = .inbox`. The Inbox screen receives an `onCompose` closure; when someone taps Compose, the closure sets `selection = .drafts`, the tab bar highlights Drafts and its content appears. The badge on Inbox reads an unread count passed in from the model, so it updates whenever that count changes. The Search tab carries no title or symbol in code: `Tab(value: .search, role: .search)` takes both from its role, and the system pins it at the trailing edge. No child view knows which tab is current unless it is handed the binding or a closure, which keeps each tab's content reusable. ## Tab roles `TabRole` (iOS 18) describes a tab's purpose. Its values in the iOS 27 SDK: | Role | Added | What it gives the tab | |---|---|---| | `.search` | iOS 18 | default "Search" title, magnifying-glass symbol, pinned in the tab bar | | `.prominent` | iOS 27 | places the tab "in a separate, trailing position of the tab bar" | Apple's sample describes the search role's defaults: the default search title, the default magnifying-glass symbol and "the default pinned behavior for search, the system automatically pins it in the tab bar". Pinned tabs sit at the **trailing** edge, which is the right side in a left-to-right language and the left side in a right-to-left one. Apple's "SwiftUI updates" page for iOS 26 adds that setting the search role takes "someone to a search tab and have a search field take the place of the tab bar". The search field itself, its suggestions and its scopes come from the `searchable` modifier on the tab's content, covered with toolbars, menus and search. ## Common mistakes - Mixing value types: with `Tab`, a value of another type does not compile against the `TabView`'s selection type; with the older `tag(_:)` form, a tag whose type differs from the binding's never matches it. - Reusing one value for two tabs, which breaks the "unique selection value" rule. - Expecting the search role to add a search field to every tab; it shapes one tab. - Treating `.prominent` as available before iOS 27. - Storing the selection in a child view, so the parent cannot switch tabs.

  • How would you add one tab per user-created mailbox and still switch to it programmatically?
    Give the selection enum a case with an associated value, such as `case mailbox(Mailbox.ID)`, and build the tabs with a `ForEach` over the mailboxes inside the `TabView` (or a `TabSection`), each `Tab` using `value: .mailbox(box.id)`. Assigning `selection = .mailbox(id)` then selects it, as long as that mailbox's tab exists.
  • What changes for the search tab on iOS 26?
    On iOS 26 and later, selecting a tab with the search role takes the person to the search tab and a search field takes the place of the tab bar. You still attach `searchable` to the tab's content to own the query text, and the role keeps providing the default title, symbol and pinned position it has had since iOS 18.

  • Binding an Int selection while the tabs carry enum values
  • Giving two tabs the same selection value
  • Thinking the search role adds a search field to every tab's content
  • Using the prominent tab role on releases before iOS 27
  • Keeping the selection inside a child, so no parent can switch tabs

Assumes the iOS 27 SDK; Tab values and the search role need iOS 18, the search field replacing the tab bar is iOS 26, and the prominent role is iOS 27.