toolbars_skill

Overview

This skill documents modern SwiftUI toolbar patterns for building customizable, searchable, and animated toolbars across Apple platforms. It focuses on practical APIs for user-configurable toolbars, search integration, transition effects, and platform-specific placements. Use it to implement robust, testable toolbar behavior in iOS, iPadOS, and macOS apps.

How this skill works

The skill inspects toolbar APIs and patterns such as .toolbar(id:), ToolbarItem(id:), ToolbarSpacer, .searchable(), and DefaultToolbarItem to compose and reposition items. It explains how to enable user customization, minimize or relocate the search field, add large-subtitle content, and attach matched transitions or shared background visibility to toolbar items. Platform differences and minimum OS availability are called out so you pick safe APIs for your deployment targets.

When to use it

• When you need user-customizable toolbars (add/remove/reorder items)
• When integrating a search field into a toolbar or minimizing it to a button
• When you want toolbar-driven transition effects or zoom animations
• When placing custom subtitle content in the navigation bar (.largeSubtitle)
• When repositioning system items like the search or sidebar across platforms

Best practices

• Use .toolbar(id:) with stable string identifiers and give every ToolbarItem its own id
• Pair .searchToolbarBehavior(.minimize) only with .searchable() so rendering and behavior match
• Apply .matchedTransitionSource(id:in:) to the ToolbarItem—not its inner Button—and match IDs with the navigationTransition source
• Use ToolbarSpacer(.fixed) and .flexible to group items logically and maintain layout consistency
• Test toolbar layouts on both iPhone and macOS; bottomBar choices and customization affordances differ by platform

Example use cases

• Create a customizable app toolbar so users can add, remove, and reorder action buttons via .toolbar(id:) and ToolbarItem(id:)
• Show a compact search button on small screens with .searchable() and .searchToolbarBehavior(.minimize)
• Reposition the system search into a bottom bar using DefaultToolbarItem(kind: .search, placement: .bottomBar)
• Animate a sheet zooming from a toolbar button using .matchedTransitionSource and navigationTransition(.zoom)
• Place a custom view in the navigation subtitle area using ToolbarItem(placement: .largeSubtitle)