On iOS 27, how does SwiftUI choose which toolbar items move into the overflow menu, and how do visibilityPriority and ToolbarOverflowMenu change that?
answer
- space decides how many render
- lower priority leaves first
- a modifier on toolbar content
- some actions always overflow
- pin the one that must stay
basics
~20 sWhen a toolbar lacks space, SwiftUI moves items into an overflow menu. On iOS 27, visibilityPriority(_:) on a toolbar item makes lower-priority items move first, and ToolbarOverflowMenu puts actions in that menu regardless of space.
solid answer
~40 sSwiftUI measures the space the toolbar has and renders as many items as fit; on iOS, iPadOS and macOS the rest can go into an overflow menu. Before iOS 27 you could not say which items to keep. iOS 27 adds `visibilityPriority(_:)`, a modifier on toolbar content such as a `ToolbarItem`, taking a `ToolbarItemVisibilityPriority`: `.automatic` by default, `.low`, `.high`, or a custom value made with `init(lowerThan:)` or `init(higherThan:)`. Lower-priority items overflow first. `ToolbarOverflowMenu { }`, or the `toolbarOverflowMenu(content:)` view modifier, declares actions that always live in the overflow menu, such as Archive, whatever the space. The `.topBarPinnedTrailing` placement anchors an item at the trailing edge while others shift. Apps deploying to iOS 17 or 18 must gate all three behind an availability check.
go deeper
Recall that a toolbar that runs out of space puts the extra items in an overflow menu, and that iOS 27 lets you rank them.
Explain the three iOS 27 tools: visibilityPriority on toolbar content, ToolbarOverflowMenu for always-hidden actions, and the pinned trailing placement.
Show judgment for real apps: rank actions by use, gate the new APIs for iOS 17 and 18 deployments, and keep a portable Menu fallback.
Treat toolbar ranking as a product rule a team agrees once: which actions stay visible, which overflow, and how that holds across iPhone, iPad and Mac.
## What overflow is A **toolbar** in SwiftUI is a declaration: you list items with placements, and the system draws them in the bars it owns. Apple's documentation for `ToolbarItemPlacement` says that on iOS, iPadOS and macOS "the system uses the space available to the toolbar when determining how many items to render", and "if not all items fit in the available space, an overflow menu may be created and remaining items placed in that menu". The overflow menu is the system-provided menu that collects the items that did not fit. Space runs out when a window is narrowed, as on **iPad** in multitasking or on **Mac**, or when a compact screen carries more items than its bar can hold. Before iOS 27 you could choose placements but not the **order** in which items leave the bar. Teams worked around that by hand-building a `Menu` labelled with an ellipsis and moving secondary actions into it themselves. ## visibilityPriority(_:): who leaves first iOS 27 adds **`visibilityPriority(_:)`**. Three facts about it matter in code review: 1. It is a modifier on **`ToolbarContent`**, so it goes on the `ToolbarItem` (or group), not on the `Button` inside it. There is no `View` version. 2. It takes a **`ToolbarItemVisibilityPriority`**. The default is `.automatic`; on iOS there are also `.low` and `.high`, and you can build relative values with `init(lowerThan:)` and `init(higherThan:)`. The type is `Comparable`. 3. Apple's documentation states the rule: "when toolbar space is limited, items with a lower priority move into the overflow menu before items with a higher priority", keeping higher-priority items visible longer as the window shrinks. ```swift .toolbar { ToolbarItem { Button("Archive", systemImage: "archivebox", action: archive) } .visibilityPriority(.low) ToolbarItem { Button("Share", systemImage: "square.and.arrow.up", action: share) } .visibilityPriority(.high) } ``` When the bar narrows, Archive goes into the overflow menu before Share does. ## ToolbarOverflowMenu: always in the menu Some actions should never take bar space, whatever the width. **`ToolbarOverflowMenu`** (iOS 27) is toolbar content whose actions "are always placed in the toolbar's overflow menu, regardless of the toolbar mode, platform, or customizability"; on iOS that is the overflow menu in the navigation bar. ```swift .toolbar { ToolbarItem(placement: .topBarTrailing) { Button("New Note", systemImage: "square.and.pencil", action: compose) } ToolbarOverflowMenu { Button("Export as PDF", action: exportPDF) Button("Move to Folder", action: move) } } ``` There is also a **`toolbarOverflowMenu(content:)`** view modifier that does the same from outside a `.toolbar` block. Both are iOS and visionOS APIs; the interface marks them unavailable on macOS, tvOS and watchOS. ## topBarPinnedTrailing: the item that must not move The iOS 27 placement **`.topBarPinnedTrailing`** anchors an item to the trailing edge of the top bar. Apple's SwiftUI updates page describes it as keeping the item in place "even as other items shift or move to the overflow menu". Use it for the one action a screen is about, such as compose in a notes app. ## Putting the three together | Tool | Question it answers | Applies to | |---|---|---| | `visibilityPriority(_:)` | Which items leave the bar first when space runs out? | A `ToolbarItem` or other toolbar content | | `ToolbarOverflowMenu` | Which actions never take bar space? | A block of toolbar content | | `.topBarPinnedTrailing` | Which item must stay at the trailing edge? | A `ToolbarItem` placement | A reasonable default for a notes screen: - compose pinned at the trailing edge; - share at `.high` priority; - archive and tag editing at `.automatic` or `.low`; - export and print in `ToolbarOverflowMenu`. ## Deploying to older releases Most apps still support iOS 17 or 18, where none of these exist. Each needs an availability check, and on older releases the system keeps deciding overflow by itself, which is the behaviour the app already had. A hand-built ellipsis `Menu` remains the portable way to group secondary actions on every release. ## Mistakes to avoid - Applying `.visibilityPriority(.high)` to the `Button` inside the item; it is a toolbar-content modifier and does not exist on views. - Assuming the overflow menu appears only on Mac; Apple lists iOS and iPadOS too. - Using `ToolbarOverflowMenu` for an action people need often; it is always one extra tap away. - Giving every item `.high` priority; when every item shares one priority, the priority no longer separates them. - Testing only on a full-width iPhone; resize an iPad window in multitasking to see the order in which items actually leave the bar.
- Why does .visibilityPriority(.high) fail to compile when attached to the Button inside a ToolbarItem?`visibilityPriority(_:)` is declared on `ToolbarContent` and `CustomizableToolbarContent`, not on `View`. A `Button` is a view, so the modifier is not found there. Attach it to the `ToolbarItem` that wraps the button, which is toolbar content, and the priority then applies to that whole item when the bar runs out of room.
- How do you get the same effect on an app that still deploys to iOS 17?On iOS 17 and 18 there is no priority API, so the system decides overflow by itself. The portable approach is to keep the bar short: place only the main actions as toolbar items and gather secondary ones into a hand-built `Menu` with an ellipsis label. On iOS 27 you can add `visibilityPriority(_:)` and `ToolbarOverflowMenu` behind an availability check.
- visibilityPriority is a view modifier you put on the Button
- Items with higher priority move into the overflow menu first
- ToolbarOverflowMenu items show in the bar while there is room
- Toolbar overflow happens only on macOS, never on iOS
- visibilityPriority has been available since iOS 17
Assumes the iOS 27 SDK: visibilityPriority(_:), ToolbarItemVisibilityPriority, ToolbarOverflowMenu and topBarPinnedTrailing are all new in iOS 27.