Swiftui 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:

ContentView()
    .toolbar(id: "main-toolbar") {
        ToolbarItem(id: "tag") {
            TagButton()
        }
        ToolbarItem(id: "share") {
            ShareButton()
        }
        ToolbarSpacer(.fixed)
        ToolbarItem(id: "more") {
            MoreButton()
        }
    }

Toolbar Spacers

ToolbarSpacer(.fixed)      // Fixed-width space
ToolbarSpacer(.flexible)   // Flexible space — pushes items apart

Anti-Patterns

// ❌ 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

@State private var searchText = ""

NavigationStack {
    RecipeList()
        .searchable(text: $searchText)
        .searchToolbarBehavior(.minimize)
}

Repositioning Search

NavigationSplitView {
    AllCalendarsView()
} detail: {
    SelectedCalendarView()
        .searchable(text: $query)
        .toolbar {
            DefaultToolbarItem(kind: .search, placement: .bottomBar)
        }
}

Transition Effects

Matched Transition from Toolbar

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))
                }
        }
    }
}

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 | | 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

• [ ] .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
• [ ] .searchable() paired with appropriate .searchToolbarBehavior()
• [ ] .matchedTransitionSource applied to ToolbarItem, not its content view
• [ ] Namespace declared with @Namespace at the view level

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ariadoss
• Source: ariadoss/superskills
• License: MIT

Install and usage instructions live in the source repository linked above.