How it works
ToolbarItemVisibilityPriority expresses how important a toolbar item is relative to the others around it, so that SwiftUI can decide which items stay visible and which collapse when there isn't room to show them all. Toolbars routinely run out of horizontal space — on compact size classes, in narrow windows, or when the system reserves room for navigation and search — and the framework needs a rule for what to keep and what to move into an overflow menu. Reach for ToolbarItemVisibilityPriority when some controls are essential to the screen and others are merely convenient, and you want the essential ones to win that contest. You apply it per item, ranking each one rather than hiding it outright.
Rank each item with defaultVisibilityPriority(_:)
The priority isn't a property of the toolbar as a whole; you attach it to the individual control inside a ToolbarItem using the defaultVisibilityPriority(_:) modifier, which takes a ToolbarItemVisibilityPriority value. In the example the
Button("Compose")andButton("Filter")each carry their own call to.defaultVisibilityPriority(_:), giving SwiftUI a per-item ranking to consult when space is tight.Promote essential controls with .high
A higher priority tells SwiftUI to keep the item on screen for as long as possible, surrendering its spot only after lower-priority items have already moved away. Here
ToolbarItemVisibilityPriority.highmarksButton("Compose")as the action the screen is really about, so it holds its place in the toolbar even as the layout tightens.Demote convenience controls with .low
A lower priority marks an item as the first to yield — it is the one SwiftUI collapses into the overflow menu when it can't fit everything. The example assigns
ToolbarItemVisibilityPriority.lowtoButton("Filter"), signaling that filtering is a nice-to-have that can step aside before the compose action does.Let placement and priority work together
ToolbarItemVisibilityPriority refines, but does not replace, the position you choose with a ToolbarItem's placement. Both buttons here sit at
.primaryAction, so placement decides where they go and the visibility priority decides which one survives when that region overflows — the two values together drive the final layout inside the.toolbarof theNavigationStack.
Button("Compose") gets ToolbarItemVisibilityPriority.low and Button("Filter") gets .high, then narrow the window until only one item fits — the survivor flips, showing that the priority, not the order, decides who stays.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 ToolbarItemVisibilityPriorityDemo: View {
var body: some View {
NavigationStack {
Text("Inbox")
.padding()
.toolbar {
ToolbarItem(placement: .primaryAction) {
Button("Compose") {}
.defaultVisibilityPriority(ToolbarItemVisibilityPriority.high)
}
ToolbarItem(placement: .primaryAction) {
Button("Filter") {}
.defaultVisibilityPriority(ToolbarItemVisibilityPriority.low)
}
}
}
}
}