NavigationSplitView

struct · iOS 16.0+ · SDK 27.1

nonisolated struct NavigationSplitView<Sidebar, Content, Detail> where Sidebar : View, Content : View, Detail : View

A view that presents views in two or three columns, where selections in leading columns control presentations in subsequent columns. You create a navigation split view with two or three columns, and typically use it as the root view in a ``Scene``. People choose one or more items in a leading column to display details about those items in subsequent columns. To create a two-column navigation split view, use the ``init(sidebar:detail:)`` initializer: @State private var employeeIds: Set<Employee.ID> = [] var body: some View { NavigationSplitView { List(model.employees, selection: $employeeIds) { employee in Text(employee.name) } } detail: { EmployeeDetails(for: employeeIds) } } In the above example, the navigation split view coordinates with the ``List`` in its first column, so that when people make a selection, the detail view updates accordingly. Programmatic changes that you make to the selection property also affect both the list appearance and the presented detail view. To create a three-column view, use the ``init(sidebar:content:detail:)`` initializer. The selection in the first column affects the second, and the selection in the second column affects the third. For example, you can show a list of departments, the list of employees in the selected department, and the details about all of the selected employees: @State private var departmentId: Department.ID? // Single selection. @State private var employeeIds: Set<Employee.ID> = [] // Multiple selection. var body: some View { NavigationSplitView { List(model.departments, selection: $departmentId) { department in Text(department.name) } } content: { if let department = model.department(id: departmentId) { List(department.employees, selection: $employeeIds) { employee in Text(employee.name) } } else { Text("Select a department") } } detail: { EmployeeDetails(for: employeeIds) } } You can also embed a ``NavigationStack`` in a column. Tapping or clicking a ``NavigationLink`` that appears in an earlier column sets the view that the stack displays over its root view. Activating a link in the same column adds a view to the stack. Either way, the link must present a data type for which the stack has a corresponding ``View/navigationDestination(for:destination:)`` modifier. 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. For example, the three-column example above shows the list of departments to start, the employees in the department after someone selects a department, and the employee details when someone selects an employee. For rows in a list that have ``NavigationLink`` instances, the list draws disclosure chevrons while in the collapsed state. ### Control column visibility You can programmatically control the visibility of navigation split view columns by creating a ``State`` value of type ``NavigationSplitViewVisibility``. Then pass a ``Binding`` to that state to the appropriate initializer --- such as ``init(columnVisibility:sidebar:detail:)`` for two columns, or the ``init(columnVisibility:sidebar:content:detail:)`` for three columns. The following code updates the first example above to always hide the first column when the view appears: @State private var employeeIds: Set<Employee.ID> = [] @State private var columnVisibility = NavigationSplitViewVisibility.detailOnly var body: some View { NavigationSplitView(columnVisibility: $columnVisibility) { List(model.employees, selection: $employeeIds) { employee in Text(employee.name) } } detail: { EmployeeDetails(for: employeeIds) } } The split view ignores the visibility control when it collapses its columns into a stack. ### Collapsed split views At narrow size classes, such as on iPhone or Apple Watch, a navigation split view collapses into a single stack. Typically SwiftUI automatically chooses the view to show on top of this single stack, based on the content of the split view's columns. For custom navigation experiences, you can provide more information to help SwiftUI choose the right column. Create a `State` value of type ``NavigationSplitViewColumn``. Then pass a `Binding` to that state to the appropriate initializer, such as ``init(preferredCompactColumn:sidebar:detail:)`` or ``init(preferredCompactColumn:sidebar:content:detail:)``. The following code shows the blue detail view when run on iPhone. When the person using the app taps the back button, they'll see the yellow view. The value of `preferredPreferredCompactColumn` will change from `.detail` to `.sidebar`: @State private var preferredColumn = NavigationSplitViewColumn.detail var body: some View { NavigationSplitView(preferredCompactColumn: $preferredColumn) { Color.yellow } detail: { Color.blue } } ### Customize a split view To specify a preferred column width in a navigation split view, use the ``View/navigationSplitViewColumnWidth(_:)`` modifier. To set minimum, maximum, and ideal sizes for a column, use ``View/navigationSplitViewColumnWidth(min:ideal:max:)``. You can specify a different modifier in each column. The navigation split view does its best to accommodate the preferences that you specify, but might make adjustments based on other constraints. To specify how columns in a navigation split view interact, use the ``View/navigationSplitViewStyle(_:)`` modifier with a ``NavigationSplitViewStyle`` value. For example, you can specify whether to emphasize the detail column or to give all of the columns equal prominence. On some platforms, `NavigationSplitView` adds a ``ToolbarDefaultItemKind/sidebarToggle`` toolbar item. Use the ``View/toolbar(removing:)`` modifier to remove the default item.

Members (0)

This type has no directly callable members in this snapshot. See the framework’s skipped declarations for unsupported APIs.

All SwiftUI types →