toolbars

# SwiftUI Toolbars Modern toolbar patterns for SwiftUI apps. Covers customizable toolbars, enhanced search integration, new placements, transition effects, and platform-specific considerations. ## When This Skill Activates Use this skill when the user: - Wants to add or customize toolbars - Asks about customizable/user-configurable toolbars - Needs search field in toolbar with specific placement - Wants toolbar item transitions or animations - Asks about toolbar placements (bottomBar, largeSubtitle, etc.) - Needs platform-specific toolbar behavior (iOS vs macOS) - Wants to reposition system toolbar items (search, sidebar) ## Decision Tree ``` What toolbar feature do you need? | +- User-customizable toolbar (add/remove/reorder items) | +- Use .toolbar(id:) with ToolbarItem(id:) | +- Search field in toolbar | +- Minimize to button -> .searchToolbarBehavior(.minimize) | +- Reposition search -> DefaultToolbarItem(kind: .search, placement:) | +- Toolbar transition/animation | +- Zoom transition from toolbar item -> .matchedTransitionSource(id:in:) | +- Hide glass background -> .sharedBackgroundVisibility(.hidden) | +- Custom subtitle area content | +- Use ToolbarItem(placement: .largeSubtitle) | +- System toolbar items with custom placement | +- DefaultToolbarItem(kind: .search/.sidebar, placement:) ``` ## API Availability | API | Minimum Version | Notes | |-----|----------------|-------| | `.toolbar { }` | iOS 14 | Basic toolbar | | `ToolbarItem(placement:)` | iOS 14 | Standard placements | | `.toolbar(id:)` | iOS 16 | Customizable toolbars | | `ToolbarItem(id:)` | iOS 16 | Items in customizable toolbars | | `ToolbarSpacer` | iOS 16 | Fixed and flexible spacers | | `.searchable()` | iOS 15 | Search integration | | `.searchToolbarBehavior(.minimize)` | iOS 17 | Minimized search button | | `DefaultToolbarItem(kind:placement:)` | iOS 18 | Reposition system items | | `ToolbarItem(placement: .largeSubtitle)` | iOS 18 | Subtitle area content | | `.matchedTransitionSource(id:in:)` | iOS 18 | Toolbar transition source | | `.sharedBackgroundVisibility()` | iOS 18 | Glass background control | ## Customizable Toolbars Allow users to personalize toolbar items by adding, removing, and rearranging: ```swift ContentView() .toolbar(id: "main-toolbar") { ToolbarItem(id: "tag") { TagButton() } ToolbarItem(id: "share") { ShareButton() } ToolbarSpacer(.fixed) ToolbarItem(id: "more") { MoreButton() } } ``` ### Toolbar Spacers ```swift ToolbarSpacer(.fixed) // Fixed-width space ToolbarSpacer(.flexible) // Flexible space — pushes items apart ``` ### Anti-Patterns ```swift // ❌ Missing IDs in customizable toolbar — items can't be customized .toolbar(id: "main") { ToolbarItem { // No id parameter ShareButton() } } // ✅ Every item needs its own ID .toolbar(id: "main") { ToolbarItem(id: "share") { ShareButton() } } ``` ## Enhanced Search Integration ### Minimized Search Renders search field as a compact button that expands on tap: ```swift @State private var searchText = "" NavigationStack { RecipeList() .searchable(text: $searchText) .searchToolbarBehavior(.minimize) } ``` ### Repositioning Search Move the default search field to a different toolbar position: ```swift NavigationSplitView { AllCalendarsView() } detail: { SelectedCalendarView() .searchable(text: $query) .toolbar { ToolbarItem(placement: .bottomBar) { CalendarPicker() } ToolbarItem(placement: .bottomBar) { Invites() } DefaultToolbarItem(kind: .search, placement: .bottomBar) ToolbarSpacer(placement: .bottomBar) ToolbarItem(placement: .bottomBar) { NewEventButton() } } } ``` ## System-Defined Toolbar Items Reposition system items with custom placements: ```swift .toolbar { DefaultToolbarItem(kind: .search, placement: .bottomBar) DefaultToolbarItem(kind: .sidebar, placement: .navigationBarLeading) } ``` ## Large Subtitle Placement Place custom content in the navigation bar subtitle area: ```swift NavigationStack { DetailView() .navigationTitle("Title") .navigationSubtitle("Subtitle") .toolbar { ToolbarItem(placement: .largeSubtitle) { CustomLargeNavigationSubtitle() } } } ``` ## Transition Effects ### Matched Transition from Toolbar Create zoom transitions originating from a toolbar button: ```swift struct ContentView: View { @State private var isPresented = false @Namespace private var namespace var body: some View { NavigationStack { DetailView() .toolbar { ToolbarItem(placement: .topBarTrailing) { Button("Show Sheet", systemImage: "globe") { isPresented = true } } .matchedTransitionSource(id: "world", in: namespace) } .sheet(isPresented: $isPresented) { SheetView() .navigationTransition( .zoom(sourceID: "world", in: namespace)) } } } } ``` ### Glass Background Control Control the shared glass background on toolbar items: ```swift ContentView() .toolbar(id: "main") { ToolbarItem(id: "build-status", placement: .principal) { BuildStatus() } .sharedBackgroundVisibility(.hidden) } ``` ## Top 5 Mistakes | # | Mistake | Fix | |---|---------|-----| | 1 | Missing `id` on ToolbarItem in customizable toolbar | Every item in `.toolbar(id:)` must have its own `id` parameter | | 2 | Using `.searchToolbarBehavior(.minimize)` without `.searchable()` | Must pair with `.searchable()` modifier — `.minimize` only affects rendering | | 3 | Putting `.matchedTransitionSource` on the Button instead of ToolbarItem | Apply `.matchedTransitionSource(id:in:)` on the `ToolbarItem`, not its content | | 4 | Using `.largeSubtitle` alongside `.navigationSubtitle()` expecting both to show | `.largeSubtitle` takes precedence — the subtitle modifier value is hidden | | 5 | Forgetting `placement:` on DefaultToolbarItem | Without explicit placement, system items use their default position | ## Platform Considerations | Platform | Recommendations | |----------|----------------| | **iOS** | Bottom bar useful on iPhones. Use `.searchToolbarBehavior(.minimize)` for space efficiency. | | **iPadOS** | Customizable toolbars valuable in productivity apps. Consider keyboard shortcuts. | | **macOS** | Users expect toolbar customization. Use spacers for logical groupings. | ## Review Checklist ### Customizable Toolbars - [ ] `.toolbar(id:)` has a unique, stable string identifier - [ ] Every `ToolbarItem` within has its own unique `id` - [ ] Spacers used to create logical groups of related items - [ ] Toolbar tested with customization panel (long-press on iPadOS, right-click on macOS) ### Search Integration - [ ] `.searchable()` paired with appropriate `.searchToolbarBehavior()` - [ ] Search placement makes sense for the platform (bottom bar on iOS, toolbar on macOS) - [ ] `DefaultToolbarItem(kind: .search)` used when repositioning is needed ### Transitions - [ ] `.matchedTransitionSource` applied to `ToolbarItem`, not its content view - [ ] Namespace declared with `@Namespace` at the view level - [ ] Source ID matches between `.matchedTransitionSource` and `.navigationTransition(.zoom)` ### Platform - [ ] Toolbar layouts tested on both iOS and macOS (if multiplatform) - [ ] Bottom bar items appropriate for small screens - [ ] Customizable toolbars provided for complex macOS apps ## References - [SwiftUI ToolbarItemPlacement](https://developer.apple.com/documentation/SwiftUI/ToolbarItemPlacement) - [SwiftUI CustomizableToolbarContent](https://developer.apple.com/documentation/SwiftUI/CustomizableToolbarContent) - [SwiftUI SearchToolbarBehavior](https://developer.apple.com/documentation/SwiftUI/SearchToolbarBehavior) - [SwiftUI DefaultToolbarItem](https://developer.apple.com/documentation/SwiftUI/DefaultToolbarItem) - [SwiftUI ToolbarSpacer](https://developer.apple.com/documentation/SwiftUI/ToolbarSpacer)