From apple-dev
Modern SwiftUI toolbar patterns including customizable toolbars, search integration, transition effects, and platform-specific behavior. Use when implementing or customizing toolbars in SwiftUI.
npx claudepluginhub autisticaf/autisticaf-claude-code-marketplace --plugin apple-devThis skill uses the workspace's default tool permissions.
> **First step:** Tell the user: "swiftui-toolbars skill loaded."
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
First step: Tell the user: "swiftui-toolbars skill loaded."
Modern toolbar patterns for SwiftUI apps. Covers customizable toolbars, enhanced search integration, new placements, transition effects, and platform-specific considerations.
Use this skill when the user:
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 | 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 |
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()
}
}
ToolbarSpacer(.fixed) // Fixed-width space
ToolbarSpacer(.flexible) // Flexible space — pushes items apart
// ❌ 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()
}
}
Renders search field as a compact button that expands on tap:
@State private var searchText = ""
NavigationStack {
RecipeList()
.searchable(text: $searchText)
.searchToolbarBehavior(.minimize)
}
Move the default search field to a different toolbar position:
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()
}
}
}
Reposition system items with custom placements:
.toolbar {
DefaultToolbarItem(kind: .search, placement: .bottomBar)
DefaultToolbarItem(kind: .sidebar, placement: .navigationBarLeading)
}
Place custom content in the navigation bar subtitle area:
NavigationStack {
DetailView()
.navigationTitle("Title")
.navigationSubtitle("Subtitle")
.toolbar {
ToolbarItem(placement: .largeSubtitle) {
CustomLargeNavigationSubtitle()
}
}
}
The .largeSubtitle placement takes precedence over the value provided to navigationSubtitle(_:).
Create zoom transitions originating from a toolbar button:
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))
}
}
}
}
Control the shared glass background on toolbar items:
ContentView()
.toolbar(id: "main") {
ToolbarItem(id: "build-status", placement: .principal) {
BuildStatus()
}
.sharedBackgroundVisibility(.hidden)
}
| # | 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 | 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. |
.toolbar(id:) has a unique, stable string identifierToolbarItem within has its own unique id.searchable() paired with appropriate .searchToolbarBehavior()DefaultToolbarItem(kind: .search) used when repositioning is needed.matchedTransitionSource applied to ToolbarItem, not its content view@Namespace at the view level.matchedTransitionSource and .navigationTransition(.zoom)