How it works
ToolbarRole describes the semantic purpose of a view's toolbar, letting SwiftUI adapt the layout, placement, and behavior of toolbar items to match a recognized interaction pattern. Rather than positioning controls by hand for every platform, you declare the role and the system arranges the toolbar appropriately — for example, applying the navigation and editing conventions an email or notes-style app expects. Reach for ToolbarRole when a screen's toolbar should follow a standard convention, especially in a navigation hierarchy where item placement differs between iOS and macOS.
Apply the role with toolbarRole(_:)
You set a
ToolbarRolenot by constructing it directly but through thetoolbarRole(_:)view modifier, which takes a role value and applies it to the content it's attached to. In the example,.toolbarRole(.editor)is placed on theListinside theNavigationStack, declaring that this screen presents an editor-style toolbar.Choose .editor for content-editing screens
ToolbarRole.editormarks a toolbar whose primary job is editing the current content, which on wider layouts spreads navigation and action items toward the leading and trailing edges the way a mail or document app does. Passing.editortotoolbarRole(_:)opts this screen into that arrangement instead of the default.Fall back to .automatic for default behavior
When you don't need a specialized layout,
ToolbarRole.automaticlets the system pick the conventional toolbar treatment for the context. It's the implicit role you'd get without the modifier, and it's the value to return to when removing.editorfromtoolbarRole(_:).Populate the toolbar that the role shapes
The role governs how items are arranged, but you still supply those items through
toolbarand give each a placement. Here the.toolbarmodifier adds aToolbarItem(placement: .primaryAction)holding theButton("Edit"), and the.editorrole determines where that primary action lands relative to the title and back button.Pair the role with a navigation context
ToolbarRoleis most meaningful inside a navigation container, since it tunes how leading navigation elements coexist with trailing actions. The example wraps everything in aNavigationStackwith.navigationTitle("Mail"), giving.editorthe title and back-affordance it reorganizes around.
.toolbarRole(.editor) to .toolbarRole(.automatic) and watch the Edit button's placement shift back to the default toolbar arrangement, especially in a wide or split layout.Example & preview
Press Run live & edit to compile it in your browser — then edit the Swift on the left and the preview re-renders live.
struct ToolbarRoleDemo: View {
var body: some View {
NavigationStack {
List {
Text("Inbox")
Text("Drafts")
Text("Sent")
}
.navigationTitle("Mail")
.toolbarRole(.editor)
.toolbar {
ToolbarItem(placement: .primaryAction) {
Button("Edit") {}
}
}
}
.padding()
}
}