Managing toolbar visibility and overflow in SwiftUI

When a SwiftUI toolbar contains more actions than the available space can hold, the system decides which items remain visible and which ones move into the overflow menu. This becomes especially important when our app can run at different window sizes.

Starting with iOS 27, SwiftUI adds several APIs that let us communicate which actions matter most, which ones belong in the overflow menu, and which one should always remain visible.

Architecture & Design Patterns for iOS

This book is a practical guide to essential architectural principles and design patterns for iOS development. It covers strategies for building maintainable apps with Swift and SwiftUI, including dependency injection, navigation, common patterns, and modularization.

LEARN MORE

If you're new to creating toolbars and placing their items, you can start with this guide to toolbars in SwiftUI. In this article, we'll focus specifically on making an existing toolbar adapt to limited space.

Prioritizing important toolbar items

By default, SwiftUI manages the visibility of toolbar items automatically. We can use the visibilityPriority modifier to tell the system which actions should remain visible for longer as the available space becomes smaller:

.toolbar {
    ToolbarItemGroup {
        Button("Undo", systemImage: "arrow.uturn.backward", action: undo)
        Button("Redo", systemImage: "arrow.uturn.forward", action: redo)
    }
    .visibilityPriority(.high)

    ToolbarItem {
        Button("Add", systemImage: "plus", action: addItem)
    }
}

In this example, SwiftUI prioritizes the Undo and Redo group over the Add button when all items no longer fit.

The available values are .low, .automatic and .high. A priority expresses the relative importance of an item; it does not reserve a fixed position or guarantee that the item is always visible.

Placing secondary actions in the overflow menu

Some actions do not need to take up toolbar space at all. We can put them inside a ToolbarOverflowMenu to make them available from the overflow menu regardless of how much room the toolbar has:

.toolbar {
    ToolbarOverflowMenu {
        Button("Duplicate", systemImage: "plus.square.on.square", action: duplicate)
        Button("Export", systemImage: "square.and.arrow.up", action: export)
        Button("Delete", systemImage: "trash", role: .destructive, action: delete)
    }
}

This is useful for secondary or less frequently used actions.

Keeping a critical action visible

For an action that should remain visible at all times, we can use the .topBarPinnedTrailing placement:

.toolbar {
    ToolbarItem(placement: .topBarPinnedTrailing) {
        Button("Share", systemImage: "square.and.arrow.up", action: share)
    }
}

The pinned item stays at the trailing edge of the top bar and does not move into the overflow menu.

Minimizing the toolbar while scrolling

We can also give scrollable content more room by minimizing the navigation bar when the user scrolls down:

ScrollView {
    LazyVStack {
        // Content
    }
}
.toolbarMinimizeBehavior(.onScrollDown, for: .navigationBar)

With this modifier, the navigation bar moves out of the way while scrolling down, and SwiftUI manages when it reappears. This behavior is independent of the visibility and overflow configuration of the toolbar items themselves.

Conclusion

Together, the toolbar APIs let us express the importance of each action while SwiftUI continues to handle the toolbar's layout across different sizes.