skip to content

In SwiftUI, how do you build a three-column NavigationSplitView for a mail app where each column's selection drives the next?

level: middleimportance: must knowfreq 55%

answer

  1. sidebar, content, detail closures
  2. List bound to optional selection state
  3. detail reads the selection
  4. placeholder when nothing is selected
  5. replaces multi-column NavigationView

basics

~20 s

Use NavigationSplitView's sidebar, content and detail closures; bind the mailbox List and the message List to optional @State selections, and let each later column read the earlier selection, showing a placeholder while it is nil.

solid answer

~40 s

I build it with `NavigationSplitView { sidebar } content: { ... } detail: { ... }`. The sidebar is `List(mailboxes, selection: $mailboxID)`, the content column looks up the selected mailbox and shows `List(messages, selection: $messageID)`, and the detail column shows the reading pane for `messageID` or a "No message selected" placeholder. Both selections are optional `@State` in the view that owns the split view, so the split view coordinates with each `List`: a tap updates the state and the next column, and setting the state in code highlights the row and updates the detail. When the mailbox changes I clear the message selection. This replaces the multi-column `NavigationView`, marked for deprecation, and works from iOS 16.

code

swift · 32 lines
swift
struct MailSplitRoot: View {
    let mailboxes: [Mailbox]
    @State private var mailboxID: Mailbox.ID?
    @State private var messageID: Message.ID?

    var body: some View {
        NavigationSplitView {
            List(mailboxes, selection: $mailboxID) { mailbox in
                Label(mailbox.name, systemImage: mailbox.symbol)
            }
            .navigationTitle("Mailboxes")
        } content: {
            if let mailbox = mailboxes.first(where: { $0.id == mailboxID }) {
                List(mailbox.messages, selection: $messageID) { message in
                    Text(message.subject)
                }
                .navigationTitle(mailbox.name)
            } else {
                Text("Select a mailbox")
            }
        } detail: {
            if let messageID {
                ReadingPane(messageID: messageID)
            } else {
                Text("No message selected")
            }
        }
        .onChange(of: mailboxID) {
            messageID = nil
        }
    }
}

go deeper

for a junior

Know the three closures, sidebar, content and detail, and that a List bound to a selection drives what the next column shows.

for a middle

Explain how optional or Set selection state coordinates the columns, why programmatic selection updates the list highlight, and the nil placeholder.

for a senior

Show how you keep selections consistent when data changes underneath them, and how you migrate a NavigationView layout.

for a principal

Decide which content earns a column versus a pushed screen, so the iPad layout stays coherent as features are added.

## What NavigationSplitView is `NavigationSplitView` (iOS 16) is SwiftUI's container for **multi-column navigation**. Apple's documentation describes it as "a view that presents views in two or three columns, where selections in leading columns control presentations in subsequent columns". A mail app is the textbook shape: | Column | Initializer label | Mail app content | |---|---|---| | leading | `sidebar:` | mailboxes | | middle (three-column only) | `content:` | messages in the selected mailbox | | trailing | `detail:` | the reading pane for the selected message | `init(sidebar:detail:)` builds two columns; `init(sidebar:content:detail:)` builds three. It is typically the root view of a scene. ## Selection drives the columns The split view does not hold your data; **selection state** does. The documented pattern is: 1. Keep one optional `@State` per selectable column in the view that owns the split view: `@State private var mailboxID: Mailbox.ID?` and `@State private var messageID: Message.ID?`. 2. In the sidebar, `List(mailboxes, selection: $mailboxID)`. 3. In the content column, look up the mailbox for `mailboxID` and show `List(mailbox.messages, selection: $messageID)`, or a prompt such as "Select a mailbox" when nothing is chosen. 4. In the detail column, show the reading pane for `messageID`, or a placeholder. Apple's documentation says the split view "coordinates with the List in its first column, so that when people make a selection, the detail view updates accordingly", and that "programmatic changes that you make to the selection property also affect both the list appearance and the presented detail view". So selecting a message from code highlights its row and opens it. A `Set` instead of an optional gives **multiple selection**; Apple's example passes a `Set<Employee.ID>` to a detail view that shows every selected item. ## Keeping the selections consistent The columns are independent state, so your code keeps them coherent: - When the mailbox changes, the old `messageID` may not exist in the new mailbox; clear it with `.onChange(of: mailboxID) { messageID = nil }`. - When a message is deleted, clear or move the selection so the detail does not show a stale message. - Look values up by identifier rather than storing copies, so an edit in the model reaches every column. ## Links instead of plain rows Rows in a split view's `List` can be plain views, as above, or `NavigationLink(value:)` rows. Apple's migration article shows the second form: a `List` bound to `selection` whose rows are `NavigationLink(color.description, value: color)`, with the detail column switching on `selection`. The list "coordinates with the navigation logic", so choosing a link updates the selection and setting the selection activates the matching link. Links make the rows read as tappable, and when the split view collapses on a narrow screen the list draws disclosure chevrons for them. Either way the **selection state remains the source of truth**: the detail column never asks which row was tapped, it only reads the state. That is also what makes a three-column layout easy to check, because setting `mailboxID` and `messageID` to known values shows the exact screen you want to inspect. ## Sizing and style - `navigationSplitViewColumnWidth(_:)` sets a preferred width on one column; `navigationSplitViewColumnWidth(min:ideal:max:)` sets bounds. The split view "does its best to accommodate the preferences". - `navigationSplitViewStyle(.balanced)` gives the columns equal prominence; `.prominentDetail` emphasises the detail column. - On some platforms the split view adds a sidebar toggle to the toolbar, which `toolbar(removing: .sidebarToggle)` removes. ## Migrating from NavigationView Apple's "Migrating to new navigation types" article tells apps with a two- or three-column `NavigationView` to switch to `NavigationSplitView`, and apps that used `NavigationLink(tag:selection:)` to move the selection to the `List`. `NavigationView` is marked for deprecation in the iOS 27 SDK with "use NavigationStack or NavigationSplitView instead". If a column needs to drill further, you embed a `NavigationStack` in that column; how the stack behaves there, and how the split view collapses on iPhone, is a separate topic. ## Common mistakes - Keeping selection inside a column's child view, so the next column cannot read it. - Forgetting the nil placeholder, which leaves an empty detail on iPad launch. - Leaving `messageID` pointing at a message from the previous mailbox. - Using one `NavigationLink(isActive:)` per row, the pattern the value-based APIs replaced. - Reaching for `NavigationView` with three child views in new code.

  • How would you support selecting several messages to show a batch-actions pane?
    Bind the message `List` to a `Set<Message.ID>` instead of an optional, and have the detail column switch on the set's count: a placeholder for zero, the reading pane for one, and a batch-actions view for several. The split view coordinates with a multi-selection `List` the same way it does with a single one.
  • Which modifiers control the column widths and the balance between columns?
    `navigationSplitViewColumnWidth(_:)` or `navigationSplitViewColumnWidth(min:ideal:max:)` on a column's root view sets that column's preferred width; the split view treats it as a preference it may adjust. `navigationSplitViewStyle(.balanced)` or `.prominentDetail` on the split view decides whether all columns share prominence or the detail is emphasised.

  • Building new multi-column layouts with NavigationView and three child views
  • Keeping the selection inside the sidebar view where the detail cannot read it
  • Leaving the message selection set after the mailbox changes
  • Leaving the detail column blank when the selection is nil
  • Using a NavigationLink(isActive:) per row to drive the detail column