Taking Control of Toolbar Items (SwiftUI)

The toolbar API adapts per platform, and by default you cannot predict which items collapse into the overflow menu on iOS. Four newer APIs make that explicit: visibilityPriority, ToolbarOverflowMenu, the topBarPinnedTrailing placement, and toolbarMinimizeBehavior.

Rank items with visibilityPriority

The same toolbar renders all items on macOS but collapses some on iOS. visibilityPriority on any ToolbarContent, with automatic, low, or high, tells SwiftUI which items to keep when space runs out.

.toolbar {
  ToolbarItemGroup(placement: .primaryAction) {
    Button("Action 1") {}
  }
  .visibilityPriority(.high)

  ToolbarItemGroup {
    Button("Action 2") {}
    Button("Action 3") {}
    Button("Action 4") {}
    Button("Action 5") {}
  }
}

Collapse on purpose with ToolbarOverflowMenu

ToolbarOverflowMenu is a group that is collapsed by default on every platform. Use it when a set of actions belongs in the overflow menu by design, instead of letting the system pick.

.toolbar {
  ToolbarItemGroup(placement: .primaryAction) {
    Button("Action 1") {}
  }
  ToolbarOverflowMenu {
    Button("Action 2") {}
    Button("Action 3") {}
  }
}

Pin an item with topBarPinnedTrailing

The topBarPinnedTrailing placement keeps an item at the trailing edge of the top bar. It only collapses when active search leaves no room.

ToolbarItemGroup(placement: .topBarPinnedTrailing) {
  Button("Action 1") {}
}

Minimize bars on scroll

toolbarMinimizeBehavior shrinks a bar while the user scrolls, and it applies to navigation, tab, bottom, and window bars.

NavigationStack { /* content and toolbar */ }
  .toolbarMinimizeBehavior(.onScrollDown, for: .navigationBar)