NavigationSplitView
A view that presents views in two or three columns, where selections in leading columns control presentations in subsequent columns.
Declaration
import { NavigationSplitView } from 'swiftui-react-native';nonisolated struct NavigationSplitView<Sidebar, Content, Detail> where Sidebar : View, Content : View, Detail : ViewInitializers
8 SwiftUI initializers back <NavigationSplitView>. The props you pass pick one.
Overview
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.
From Apple’s SwiftUI documentation. Code samples there are Swift.
Relationships
Conforms to
- View
See also
More in Navigation.
- LinkA control for navigating to a URL.
- NavigationLinkA view that controls a navigation presentation.
- NavigationStackA view that displays a root view and enables you to present additional views over the root view.
- ShareLinkA view that controls a sharing presentation.
- TabThe content for a tab and the tab's associated tab item in a tab view.
- TabsTabbed navigation (SwiftUI TabView with Tab). Each Trigger declares a tab; the Content with the same value is its page.
- TabSectionA container that you can use to add hierarchy within a tab view.
- TabViewA view that switches between multiple child views using interactive user interface elements.