A structure that defines the placement of a toolbar item.
There are two types of placements:
- Semantic placements, such as ``ToolbarItemPlacement/principal`` and
``ToolbarItemPlacement/navigation``, denote the intent of the
item being added. SwiftUI determines the appropriate placement for
the item based on this intent and its surrounding context, like the
current platform.
- Positional placements, such as
``ToolbarItemPlacement/navigationBarLeading``, denote a precise
placement for the item, usually for a particular platform.
In iOS, iPadOS, and macOS, the system uses the space available to the
toolbar when determining how many items to render in the toolbar. If not
all items fit in the available space, an overflow menu may be created
and remaining items placed in that menu.
Members (20)
get · iOS 26.0+
largeTitle
TypeScript
static get largeTitle(): ToolbarItemPlacement
Swift declaration
static let largeTitle: ToolbarItemPlacement
A placement for items in the navigation bar's title area.
The view appears when the navigation bar renders its title
out-of-line, and takes precedence over the value provided to the
``View.navigationTitle(_:)`` modifier.
struct ContentView: View {
var body: some View {
NavigationStack {
DetailView()
.navigationTitle("Title")
.navigationSubtitle("Subtitle")
.toolbar {
ToolbarItem(placement: .largeTitle) {
CustomLargeNavigationTitle()
}
}
}
}
}
get · iOS 14.0+
navigation
TypeScript
static get navigation(): ToolbarItemPlacement
Swift declaration
static let navigation: ToolbarItemPlacement
A placement for navigation actions.
Navigation actions allow the user to move between contexts.
For example, the forward and back buttons of a web browser
are navigation actions.
In macOS and in Mac Catalyst apps, the system places navigation items
in the leading edge of the toolbar ahead of the inline title if that is
present in the toolbar.
In iOS, iPadOS, and tvOS, navigation items appear in the leading
edge of the navigation bar. If a system navigation item such as a back
button is present in a compact width, it instead appears in
the ``ToolbarItemPlacement/primaryAction`` placement.
get · iOS 26.0+
largeSubtitle
TypeScript
static get largeSubtitle(): ToolbarItemPlacement
Swift declaration
static let largeSubtitle: ToolbarItemPlacement
A placement for items in the navigation bar's large title subtitle
area.
The view appears when the navigation bar renders its title
out-of-line, and takes precedence over the value provided to the
``View.navigationSubtitle(_:)`` modifier.
struct ContentView: View {
var body: some View {
NavigationStack {
DetailView()
.navigationTitle("Title")
.navigationSubtitle("Subtitle")
.toolbar {
ToolbarItem(placement: .largeSubtitle) {
CustomLargeNavigationSubtitle()
}
}
}
}
}
get · iOS 14.0+
primaryAction
TypeScript
static get primaryAction(): ToolbarItemPlacement
Swift declaration
static let primaryAction: ToolbarItemPlacement
A placement for the primary action.
A primary action is a more frequently used action for the current
context. For example, a button the user clicks or taps to compose a new
message in a chat app.
In macOS and in Mac Catalyst apps, the location for the primary action
is the leading edge of the toolbar.
In iOS, iPadOS, and tvOS, the location for the primary action is
the trailing edge of the navigation bar.
In watchOS the system places the primary action beneath the
navigation bar; the user reveals the action by scrolling.
get · iOS 14.0+
topBarLeading
TypeScript
static get topBarLeading(): ToolbarItemPlacement
Swift declaration
@backDeployed(before: iOS 17.0, tvOS 17.0)
static var topBarLeading: ToolbarItemPlacement { get }
A placement for items in the leading edge of the top bar.
On watchOS, iOS, and tvOS, the top bar is the navigation bar.
get · iOS 14.0+
topBarTrailing
TypeScript
static get topBarTrailing(): ToolbarItemPlacement
Swift declaration
@backDeployed(before: iOS 17.0, tvOS 17.0)
static var topBarTrailing: ToolbarItemPlacement { get }
A placement for items in the trailing edge of the top bar.
On watchOS, iOS, and tvOS, the top bar is the navigation bar.
get · iOS 16.0+
secondaryAction
TypeScript
static get secondaryAction(): ToolbarItemPlacement
Swift declaration
static let secondaryAction: ToolbarItemPlacement
A placement for secondary actions.
A secondary action is a frequently used action for the current context
but is not a requirement for the current context to function.
get · iOS 14.0+
destructiveAction
TypeScript
static get destructiveAction(): ToolbarItemPlacement
Swift declaration
static let destructiveAction: ToolbarItemPlacement
A placement for destructive actions in a modal interface.
Destructive actions represent the opposite of a confirmation action.
For example, a button labeled "Don't Save" that allows the user to
discard unsaved changes to a document before quitting.
In macOS and in Mac Catalyst apps, the system places `destructiveAction`
items in the leading edge of the sheet and gives them a special
appearance to caution against accidental use.
In iOS, tvOS, and watchOS, the system places `destructiveAction` items
in the trailing edge of the navigation bar.
get · iOS 14.0+
cancellationAction
TypeScript
static get cancellationAction(): ToolbarItemPlacement
Swift declaration
static let cancellationAction: ToolbarItemPlacement
A placement for cancellation actions in a modal interface.
Cancellation actions dismiss the modal interface without taking any
action, usually by tapping or clicking a Cancel button.
In macOS and in Mac Catalyst apps, the system places
`cancellationAction` items on the trailing edge of the sheet but
places them before any ``confirmationAction`` items.
In iOS, iPadOS, tvOS, and watchOS, the system places
`cancellationAction` items on the leading edge of the navigation bar.
get · iOS 14.0+
confirmationAction
TypeScript
static get confirmationAction(): ToolbarItemPlacement
Swift declaration
static let confirmationAction: ToolbarItemPlacement
A placement for confirmation actions in a modal interface.
Use confirmation actions to receive user confirmation of a
particular action. An example of a confirmation action would be
an action with the label "Add" to add a new event to the calendar.
In macOS and in Mac Catalyst apps, the system places
`confirmationAction` items on the trailing edge
in the trailing-most position of the sheet and gain the apps accent
color as a background color.
In iOS, iPadOS, and tvOS, the system places `confirmationAction` items
in the same location as a ``ToolbarItemPlacement/primaryAction``
placement.
In watchOS, the system places `confirmationAction` items in the
trailing edge of the navigation bar.
get · iOS 14.0+ · Deprecated in iOS 100000.0
navigationBarLeading
TypeScript
static get navigationBarLeading(): ToolbarItemPlacement
Swift declaration
static let navigationBarLeading: ToolbarItemPlacement
A placement for items in the leading edge of the navigation bar.
get · iOS 27.0+
topBarPinnedTrailing
TypeScript
static get topBarPinnedTrailing(): ToolbarItemPlacement
Swift declaration
static let topBarPinnedTrailing: ToolbarItemPlacement
A placement that pins the item to the trailing edge of the toolbar.
Pinned items only move to the overflow menu when search is active
and there isn't enough room.
On iOS and visionOS, the top bar is the navigation bar.
get · iOS 14.0+ · Deprecated in iOS 100000.0
navigationBarTrailing
TypeScript
static get navigationBarTrailing(): ToolbarItemPlacement
Swift declaration
static let navigationBarTrailing: ToolbarItemPlacement
A placement for items in the trailing edge of the navigation bar.
get · iOS 14.0+
title
TypeScript
static get title(): ToolbarItemPlacement
Swift declaration
@export(implementation) static var title: ToolbarItemPlacement { get }
A placement for items in the title area of the navigation bar.
The view appears when the navigation bar renders its title inline,
and takes precedence over the value provided to the
``View.navigationTitle(_:)`` modifier.
struct ContentView: View {
var body: some View {
NavigationStack {
DetailView()
.navigationTitle("Title")
.navigationSubtitle("Subtitle")
.toolbar {
ToolbarItem(placement: .title) {
CustomNavigationTitle()
}
}
}
}
}
get · iOS 14.0+
status
TypeScript
static get status(): ToolbarItemPlacement
Swift declaration
static let status: ToolbarItemPlacement
A placement for items that represents a change in status.
Status items are informational in nature, and don't represent an
action that can be taken by the user. For example, a message that
indicates the time of the last communication with the server to check
for new messages.
In macOS and in Mac Catalyst apps, the system places status items in
the center of the toolbar.
In iOS and iPadOS, the system places status items in the center of the
bottom toolbar.
In tvOS, this placement is only available from within the sidebar of a
``NavigationSplitView``. The system places status items in the center
of the bottom toolbar within the navigation sidebar. It has no effect
if used elsewhere.
get · iOS 15.0+
keyboard
TypeScript
static get keyboard(): ToolbarItemPlacement
Swift declaration
static let keyboard: ToolbarItemPlacement
A placement for items in the keyboard section.
On iOS, keyboard items are above the software keyboard when present,
or at the bottom of the screen when a hardware keyboard is attached.
On macOS, keyboard items will be placed inside the Touch Bar.
A `FocusedValue` can be used to adjust the content of the keyboard bar
based on the currently focused view. In the example below, the keyboard
bar gains additional buttons only when the appropriate `TextField` is
focused.
enum Field {
case suit
case rank
}
struct KeyboardBarDemo : View {
@FocusedValue(\.field) var field: Field?
var body: some View {
HStack {
TextField("Suit", text: $suitText)
.focusedValue(\.field, .suit)
TextField("Rank", text: $rankText)
.focusedValue(\.field, .rank)
}
.toolbar {
ToolbarItemGroup(placement: .keyboard) {
if field == .suit {
Button("♣️", action: {})
Button("♥️", action: {})
Button("♠️", action: {})
Button("♦️", action: {})
}
DoneButton()
}
}
}
}
get · iOS 26.0+
subtitle
TypeScript
static get subtitle(): ToolbarItemPlacement
Swift declaration
static let subtitle: ToolbarItemPlacement
A placement for items in the navigation bar's inline subtitle area.
The view appears when the navigation bar renders its title
inline, and takes precedence over the value provided to the
``View.navigationSubtitle(_:)`` modifier.
struct ContentView: View {
var body: some View {
NavigationStack {
DetailView()
.navigationTitle("Title")
.navigationSubtitle("Subtitle")
.toolbar {
ToolbarItem(placement: .subtitle) {
CustomNavigationSubtitle()
}
}
}
}
}
get · iOS 14.0+
automatic
TypeScript
static get automatic(): ToolbarItemPlacement
Swift declaration
static let automatic: ToolbarItemPlacement
A placement the system positions automatically.
In macOS and in Mac Catalyst apps, the system places items in the
current toolbar section in order of leading to trailing. On watchOS,
only the first item appears, pinned beneath the navigation bar.
In iPadOS, the system places items in the center of the navigation bar
if the navigation bar supports customization. Otherwise, it places
items in the trailing position of the navigation bar.
In iOS, and tvOS, the system places items in the trailing
position of the navigation bar.
In iOS, iPadOS, and macOS, the system uses the space available to the
toolbar when determining how many items to render in the toolbar. If not
all items fit in the available space, an overflow menu may be created
and remaining items placed in that menu.
get · iOS 14.0+
bottomBar
TypeScript
static get bottomBar(): ToolbarItemPlacement
Swift declaration
static let bottomBar: ToolbarItemPlacement
A placement for items in the bottom toolbar.
On tvOS, this applies only within the sidebar of a
``NavigationSplitView``. It has no effect if used elsewhere.
get · iOS 14.0+
principal
TypeScript
static get principal(): ToolbarItemPlacement
Swift declaration
static let principal: ToolbarItemPlacement
A placement for the principal item section.
Principal actions are key units of functionality that receive prominent
placement. For example, the location field for a web browser is a
principal item.
In macOS and in Mac Catalyst apps, the system places the principal item
in the center of the toolbar.
In iOS, iPadOS, and tvOS, the system places the principal item in the
center of the navigation bar. This item takes precedent over a title
specified through ``View/navigationTitle``.
