In SwiftUI, how do you build a three-column NavigationSplitView for a mail app where each column's selection drives the next?
answer
- sidebar, content, detail closures
- List bound to optional selection state
- detail reads the selection
- placeholder when nothing is selected
- replaces multi-column NavigationView
basics
~20 sUse 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 sI 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 linesstruct 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
Know the three closures, sidebar, content and detail, and that a List bound to a selection drives what the next column shows.
Explain how optional or Set selection state coordinates the columns, why programmatic selection updates the list highlight, and the nil placeholder.
Show how you keep selections consistent when data changes underneath them, and how you migrate a NavigationView layout.
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