On iPhone a SwiftUI NavigationSplitView collapses into one stack; how does SwiftUI pick what shows there, and how do columnVisibility and preferredCompactColumn behave?
answer
- narrow width means a single stack
- the deepest column with useful content
- visibility binding ignored when collapsed
- iOS 17 column hint for compact
- detail stack inside a column
basics
~10 sIn narrow widths NavigationSplitView collapses into one stack and shows the last column with useful content, driven by selection. columnVisibility is ignored while collapsed; preferredCompactColumn (iOS 17) chooses which column sits on top.
solid answer
~40 sAt narrow sizes, such as iPhone or iPad in Slide Over, `NavigationSplitView` collapses its columns into a single stack and shows the last column that has useful information, so selection decides the depth: no mailbox selected means the mailbox list, a selected message means the reading pane. `columnVisibility` with `NavigationSplitViewVisibility` (`.all`, `.doubleColumn`, `.detailOnly`, `.automatic`) only matters when the columns are side by side; Apple's documentation says the split view ignores it when it collapses. For the collapsed case, iOS 17 added `preferredCompactColumn`, a binding to `NavigationSplitViewColumn` (`.sidebar`, `.content`, `.detail`) that picks the column on top and changes as the person navigates back. If a column embeds a `NavigationStack`, a link from an earlier column sets that stack's view over its root.
code
swift · 28 linesstruct MailSplitView: View {
@State private var visibility: NavigationSplitViewVisibility = .all
@State private var compactColumn: NavigationSplitViewColumn = .sidebar
@State private var mailboxID: Mailbox.ID?
@State private var messageID: Message.ID?
@State private var detailPath: [Attachment] = []
var body: some View {
NavigationSplitView(
columnVisibility: $visibility, // ignored when collapsed
preferredCompactColumn: $compactColumn // consulted when collapsed
) {
MailboxList(selection: $mailboxID)
} content: {
MessageList(mailboxID: mailboxID, selection: $messageID)
} detail: {
NavigationStack(path: $detailPath) {
ReadingPane(messageID: messageID)
.navigationDestination(for: Attachment.self) { attachment in
AttachmentView(attachment: attachment)
}
}
}
.onChange(of: messageID) {
detailPath.removeAll()
}
}
}go deeper
Remember that on iPhone a NavigationSplitView turns into a single navigation stack driven by what is selected.
Explain the NavigationSplitViewVisibility values and why they only apply when columns are side by side.
Diagnose collapse bugs: visibility ignored when collapsed, preferredCompactColumn from iOS 17, and a detail stack path that outlives a selection change.
Argue for one selection-driven hierarchy that adapts across iPad and iPhone, instead of separate per-device navigation code paths.
## One model, two shapes The reason interviewers ask about `NavigationSplitView` is that **one declaration serves both iPad and iPhone**. On a regular-width iPad the columns sit side by side. Apple's documentation says that "on watchOS and tvOS, and with narrow sizes like on iPhone or on iPad in Slide Over, the navigation split view collapses all of its columns into a stack, and shows the last column that displays useful information". The same view can switch between the two shapes at run time when an iPad window is resized. ## What the collapsed stack shows In the collapsed stack SwiftUI "automatically chooses the view to show on top of this single stack, based on the content of the split view's columns". Apple walks through a three-column example: the stack shows the departments first, the employees after someone selects a department, and the employee details after someone selects an employee. For a mail app that means: - nothing selected: the mailbox list; - a mailbox selected: that mailbox's messages, with the mailboxes one step back; - a message selected: the reading pane, with a back button to the messages. Rows built with `NavigationLink` draw disclosure chevrons in the collapsed state. Because the stack follows the **selection state**, setting a selection in code moves the collapsed stack too, so the same state works in both shapes. ## `columnVisibility`: for side-by-side columns only `NavigationSplitViewVisibility` controls which leading columns are visible when columns are side by side: | Value | Effect | |---|---| | `.all` | show every column | | `.doubleColumn` | hide the leading column of a three-column split view | | `.detailOnly` | hide everything but the trailing column | | `.automatic` | let the platform decide for the current context | You pass a binding through `init(columnVisibility:sidebar:detail:)` or the three-column form. Two limits matter: the documentation states that "the split view ignores the visibility control when it collapses its columns into a stack", and that "some platforms don't respect every option", for example macOS always shows the content column. ## `preferredCompactColumn`: for the collapsed stack (iOS 17) `NavigationSplitViewColumn`, with `.sidebar`, `.content` and `.detail`, was added in iOS 17 "to control which column of the navigation split view appears on top of the collapsed stack". You pass it with `init(preferredCompactColumn:sidebar:detail:)`, the three-column form, or together with visibility through `init(columnVisibility:preferredCompactColumn:sidebar:content:detail:)`. The binding is two-way: in Apple's example the value changes from `.detail` to `.sidebar` when the person taps back. ## A column that drills further A column can embed a `NavigationStack`. The documentation describes the two cases: tapping a `NavigationLink` in an **earlier** column "sets the view that the stack displays over its root view", and activating a link in the **same** column adds a view to the stack. Either way the stack needs a `navigationDestination(for:destination:)` for the link's data type. If the detail column's stack has a bound path, consider clearing it when the selected message changes, so an attachment opened from the previous message does not stay on top of the new one. ## Checking both shapes during development - Run the same build on an iPhone simulator and an iPad simulator, and on iPad use a narrow multitasking size such as Slide Over to watch the split view collapse and expand at run time. - Start from three states, nothing selected, a mailbox selected and a message selected, and confirm the collapsed stack shows the expected depth. - Tap back in the collapsed stack and check that `preferredCompactColumn` and the selections change the way your code expects. - Resize while the detail stack has pushed views, and confirm the path survives or is reset on purpose. Because one selection model drives both shapes, most bugs here come from state that lives somewhere other than the view that owns the split view. ## Diagnosing a misbehaving split view 1. **"`.detailOnly` is set, but iPhone launches on the sidebar."** Visibility is ignored when collapsed; use `preferredCompactColumn` for the compact case. 2. **"iPhone shows an empty placeholder on launch."** Usually the preferred compact column points at the detail while nothing is selected; start on `.sidebar` or make sure a selection exists. 3. **"A pushed screen from the old message stays after picking a new one."** The detail stack's path survives the selection change; reset it in `onChange(of:)`. 4. **"State differs between iPad and iPhone."** Selection lives in a column's child view; lift it to the view that owns the split view. The toolbar's sidebar toggle and other toolbar items are covered with toolbars; changing the tab structure itself between size classes is a `TabView` concern.
- Why not just read horizontalSizeClass and switch between a NavigationStack and a split view yourself?Two hand-built hierarchies duplicate the navigation and can lose state held inside them whenever an iPad window crosses the size boundary, because the switch replaces one view tree with another. NavigationSplitView already collapses and expands one hierarchy while keeping the selection state, so the same state shows the right screen in both shapes.
- What happens to the preferredCompactColumn binding when someone taps back on iPhone?The split view writes the new top column into the binding. Apple's example starts at `.detail`; after the person taps back the value becomes `.sidebar`. Because it is two-way, your code can read it to know which column is showing in the collapsed stack, and set it to move there.
- Expecting columnVisibility = .detailOnly to control what iPhone shows first
- Assuming preferredCompactColumn exists on iOS 16
- Switching between NavigationStack and NavigationSplitView by size class by hand
- Expecting every visibility value to be honoured on every platform
- Thinking a sidebar link pushes onto the sidebar instead of setting the detail stack