In SwiftUI, how do you put a compose button and a sort menu into a screen's navigation bar with toolbar and ToolbarItem placements?
answer
- a modifier on the content, not the bar
- one wrapper per control, or a group
- semantic intent vs exact position
- topBarTrailing replaced navigationBarTrailing
basics
~20 sApply .toolbar to the screen's content inside a NavigationStack and wrap each control in a ToolbarItem or ToolbarItemGroup with a placement such as .topBarTrailing, .topBarLeading, .principal or .bottomBar; SwiftUI then lays the items out in the bars.
solid answer
~40 sThe `toolbar(content:)` modifier populates the toolbar or navigation bar for the view it is applied to, so on iPhone I attach it, together with `navigationTitle`, to the content view inside a `NavigationStack`; a pushed screen brings its own items. Each control goes in a `ToolbarItem(placement:)`, or related controls go in one `ToolbarItemGroup(placement:)`, which gives SwiftUI the grouping it needs for correct spacing. Placements are either semantic, such as `.primaryAction`, `.confirmationAction` or `.principal`, where SwiftUI chooses the spot per platform, or explicit, such as `.topBarLeading`, `.topBarTrailing`, `.bottomBar` and `.keyboard`. For a notes list I would put the compose button at `.topBarTrailing` and a sort `Menu` at `.topBarLeading`. `.topBarTrailing` is the current name; `.navigationBarTrailing` is marked for deprecation.
code
swift · 24 linesstruct EditNoteView: View {
@Binding var text: String
let onSave: () -> Void
let onCancel: () -> Void
var body: some View {
NavigationStack {
TextEditor(text: $text)
.navigationTitle("Edit Note")
.navigationBarTitleDisplayMode(.inline)
.toolbar {
ToolbarItem(placement: .cancellationAction) {
Button("Cancel", action: onCancel)
}
ToolbarItem(placement: .confirmationAction) {
Button("Save", action: onSave)
}
ToolbarItemGroup(placement: .bottomBar) {
Text("\(text.count) characters")
}
}
}
}
}go deeper
Recall the shape: .toolbar on the content inside a NavigationStack, a ToolbarItem with a placement around each control, and navigationTitle next to it.
Explain semantic versus explicit placements, why ToolbarItemGroup gives correct spacing, and how each pushed screen brings its own items and title.
Show judgment in shared code: prefer semantic placements across iPhone, iPad and Mac, replace the deprecated navigationBar placements, and expect overflow when space runs out.
Frame toolbar placement as a consistency rule a design system can fix: which actions are primary, which go to menus, and how one declaration adapts per platform.
## What the toolbar modifier does In SwiftUI a **toolbar** is not a view you place in your layout. It is a set of items you *declare* on a view, and the system decides how to draw them in the bars it owns: the **navigation bar** at the top of an iPhone screen, the **bottom toolbar**, the keyboard's accessory bar, or a window toolbar on iPad and Mac. Apple's documentation describes `toolbar(content:)` as the modifier that "populates the toolbar or navigation bar with the specified items". Because the items belong to the view that declares them, the usual place for `.toolbar` is the **content view inside a `NavigationStack`**, next to `navigationTitle`. When a new screen is pushed, its own `.toolbar` and title replace the previous screen's in the navigation bar. On iPhone the top bar is supplied by the navigation container, so a screen that is not inside a `NavigationStack` (or a split view) has no navigation bar for its top-bar items to land in. ## Wrapping items: ToolbarItem and ToolbarItemGroup - **`ToolbarItem(placement:content:)`** wraps one control and gives it a placement. It has existed since iOS 14. - **`ToolbarItemGroup(placement:content:)`** wraps several related controls that share one placement, such as the buttons of a bottom bar. - A bare `Button` inside `.toolbar { }` also compiles, because there is an overload that accepts plain views, but then you give up saying where it goes. Apple notes that wrapping related controls in a `ToolbarItemGroup` gives a one-to-one mapping between controls and toolbar items, "which results in the correct layout and spacing on each platform". ## Choosing a placement `ToolbarItemPlacement` has two families, and the difference matters when the same code runs on iPhone, iPad and Mac: | Kind | Examples | What SwiftUI does | |---|---|---| | Semantic | `.automatic`, `.principal`, `.primaryAction`, `.confirmationAction`, `.cancellationAction`, `.destructiveAction`, `.navigation` | Reads your **intent** and picks the spot for the current platform and context | | Explicit | `.topBarLeading`, `.topBarTrailing`, `.bottomBar`, `.keyboard` | Puts the item in a **specific bar position**, usually for one platform | A few placements an iOS engineer meets every week: 1. `.topBarTrailing` and `.topBarLeading`: the trailing and leading edges of the navigation bar. These names were added to the SDK with back-deployment, so they work on every release an app still supports; the older `.navigationBarTrailing` and `.navigationBarLeading` are marked for deprecation with the message "use topBarTrailing instead". 2. `.principal`: the centre of the navigation bar, where the title would sit; use it for a custom title view such as a segmented control. 3. `.bottomBar`: the toolbar along the bottom of the screen on iPhone. 4. `.keyboard`: an accessory bar above the software keyboard (iOS 15 and later). 5. `.confirmationAction` and `.cancellationAction`: Done and Cancel in a modal form, placed where the platform expects them. When the bar runs out of room, Apple's documentation says the system may create an **overflow menu** and place the remaining items there on iOS, iPadOS and macOS. ## A worked example: a notes list ```swift struct NotesListView: View { let notes: [Note] let onCompose: () -> Void let onSort: (SortOrder) -> Void var body: some View { NavigationStack { List(notes) { note in Text(note.title) } .navigationTitle("Notes") .toolbar { ToolbarItem(placement: .topBarTrailing) { Button("New Note", systemImage: "square.and.pencil", action: onCompose) } ToolbarItem(placement: .topBarLeading) { Menu("Sort", systemImage: "arrow.up.arrow.down") { Button("Oldest First") { onSort(.forward) } Button("Newest First") { onSort(.reverse) } } } } } } } ``` The `.toolbar` sits on the `List`, inside the stack, beside the title. The compose action is the screen's main action, so it goes at the trailing edge; the sort `Menu` is itself a toolbar item, so a tap opens its choices. ## The title that shares the bar - **`navigationTitle(_:)`** sets the text shown in the navigation bar when the view is displayed inside a navigation container. - **`navigationBarTitleDisplayMode(_:)`** (iOS only) chooses `.large`, `.inline` or `.automatic` for that title. - **`toolbarTitleDisplayMode(_:)`** (iOS 17) is the cross-platform form and adds `.inlineLarge`. ## Mistakes reviewers catch - Putting `.toolbar` on a view with no navigation container and wondering why the top-bar buttons never appear. - Using `.navigationBarTrailing` in new code instead of `.topBarTrailing`. - Scattering related bottom-bar buttons as separate items rather than one `ToolbarItemGroup`. - Hard-coding explicit placements in code meant for iPhone and Mac, where a semantic placement such as `.primaryAction` would adapt by itself.
- Why might a semantic placement such as .primaryAction be better than .topBarTrailing in shared iPhone and Mac code?A semantic placement states what the item is for and lets SwiftUI choose the spot for each platform and context, in the navigation bar on iPhone and in the window toolbar on Mac. `.topBarTrailing` names a bar position that only makes sense where there is a top navigation bar, and it is unavailable on macOS, so shared code would need conditional compilation.
- When a pushed screen declares its own toolbar, what happens to the previous screen's items?The toolbar belongs to the view that declares it. When `NavigationStack` pushes a destination, the navigation bar shows the destination's `navigationTitle` and `.toolbar` items; the previous screen's items come back when it is popped. That is why items are declared on each screen's content rather than once on the stack.
- Toolbar items are views you position yourself inside the layout
- navigationBarTrailing is still the recommended placement for new code
- A toolbar shows top-bar buttons even without any navigation container
- ToolbarItemGroup is required for the toolbar modifier to compile
- principal places the item at the trailing edge of the bar