SwiftUI NavigationSplitView Columns and Width
NavigationSplitView builds two- and three-column interfaces for iPad and Mac, with columnVisibility control, navigationSplitViewColumnWidth, and automatic iPhone collapsing.
import SwiftUI
struct MailSplit: View {
@State private var visibility: NavigationSplitViewVisibility = .all
@State private var selectedBox: String?
var body: some View {
NavigationSplitView(columnVisibility: $visibility) {
List(["Inbox", "Sent", "Drafts"], id: \.self,
selection: $selectedBox) { box in
Label(box, systemImage: "tray")
}
.navigationSplitViewColumnWidth(min: 180, ideal: 220, max: 280)
.navigationTitle("Mailboxes")
} detail: {
Text(selectedBox.map { "\($0) messages" } ?? "Select a mailbox")
}
}
}
Columns as closures
Two-column splits take sidebar and detail builders; the three-column form inserts content between them for list → sublist → detail apps. Each column hosts its own navigation context, so detail screens can still push deeper with an embedded NavigationStack.
Selection wiring
The split view shines when columns are linked by selection state:
List(boxes, selection: $selectedBox) { … } // sidebar
// detail reads selectedBoxOn iPad this updates the adjacent column; on iPhone the same code becomes a push — adaptation without conditionals.
Visibility and width
columnVisibility is a binding, so a Focus Mode button can set .detailOnly and a Browse button can restore .all. Column width hints — navigationSplitViewColumnWidth(min:ideal:max:) — apply per column; the system balances them with platform conventions.
Styles
navigationSplitViewStyle(.balanced) keeps sidebar and detail visible together where space permits, while .prominentDetail keeps detail full-size and floats the sidebar over it.
Common mistakes
- Recreating split behavior with HStacks and losing the free iPhone adaptation.
- Forgetting an empty-selection detail placeholder, leaving a blank pane at launch.
- Fighting the sidebar toggle by also adding custom show/hide buttons that bypass columnVisibility.
Related reference
NavigationStack hosts push navigation. Configure titles and display modes, place bar items with toolbar, and control bar background and visibility with toolbarBackground.
Bind a path to NavigationStack and navigation history becomes data: append to push, removeLast to pop, clear to return to root, mix types with NavigationPath.
Table presents multi-column data with selectable rows and sortable headers on Mac and iPad, collapsing gracefully to its first column on iPhone.