protocol CustomizableToolbarContent : ToolbarContent where Self.Body : CustomizableToolbarContent
Conforming types represent items that can be placed in various locations
in a customizable toolbar.
Members (8)
method · iOS 27.1+
axisBehavior
Swift declaration
nonisolated func axisBehavior(_ behavior: ToolbarItemAxisBehavior) -> some CustomizableToolbarContent
The bar axis behavior of the toolbar item.
Use this modifier to control which bar axes a toolbar item can
appear in.
The following example restricts an item to the horizontal axis.
The item can only appear in a horizontal bar.
.toolbar(id: "main") {
ToolbarItem(id: "enable") {
Toggle(isOn: $isOn) { ... }
}
.axisBehavior(.horizontalOnly)
}
If both horizontal & vertical bars are present and the item is
`.verticalPreferred`, the system prefers placing the item
vertically.
- Parameter behavior: The axis behavior of the item.
method · iOS 27.0+
visibilityPriority
Swift declaration
func visibilityPriority(_ priority: ToolbarItemVisibilityPriority) -> some CustomizableToolbarContent
Defines the visibility priority for a toolbar item.
When toolbar space is limited, items with a lower priority
move into the overflow menu before items with a higher priority.
The default is ``ToolbarItemVisibilityPriority/automatic``.
In the following example, `PrimaryControl` stays visible in
the toolbar longer than `SecondaryControl`:
struct RootView: View {
var body: some View {
ContentView()
.toolbar {
ToolbarItem {
SecondaryControl()
}
ToolbarItem {
PrimaryControl()
}
.visibilityPriority(.high)
}
}
}
- Parameter priority: The visibility priority for this toolbar
item.
method · iOS 16.0+ · Deprecated in iOS 16.0
defaultCustomization
Swift declaration
func defaultCustomization() -> some CustomizableToolbarContent
Configures customizable toolbar content with the default visibility
and options.
Use the ``CustomizableToolbarContent/defaultCustomization(_:options:)``
modifier providing either a `defaultVisibility` or `options` instead.
Configures the way customizable toolbar items with the default
behavior behave.
Default customizable items support a variety of edits by the user.
* A user can add an item that is not in the toolbar.
* A user can remove an item that is in the toolbar.
* A user can move an item within the toolbar.
By default, all default customizable items will be initially
present in the toolbar. Provide a value of
``Visibility/hidden`` to this modifier to specify that items should
initially be hidden from the user, and require them to add those items
to the toolbar if desired.
ContentView()
.toolbar(id: "main") {
ToolbarItem(id: "new") {
// new button here
}
.defaultCustomization(.hidden)
}
You can ensure that the user can always use an item with default
customizability, even if it's removed from the customizable toolbar. To
do this, provide the ``ToolbarCustomizationOptions/alwaysAvailable``
option. These items will remain in the overflow if the user removes them
from the toolbar.
Provide a value of ``ToolbarCustomizationOptions/alwaysAvailable`` to
the options parameter of this modifier to receive this behavior.
ContentView()
.toolbar(id: "main") {
ToolbarItem(id: "new") {
// new button here
}
.defaultCustomization(options: .alwaysAvailable)
}
- Parameters:
- defaultVisibility: The default visibility of toolbar content
with the default customization behavior.
- options: The customization options to configure the behavior
of toolbar content with the default customization behavior.
method · iOS 27.0+
contentMarginsRemoved
Swift declaration
nonisolated func contentMarginsRemoved(_ removed: Bool = true) -> some CustomizableToolbarContent
Configures whether the content margins are removed.
Use this modifier to remove the default padding around a toolbar item's
content. This is useful for content that goes to the edge of the item.
.toolbar(id: "main") {
ToolbarItem(id: "custom") {
CustomButton()
}
.contentMarginsRemoved()
}
- Parameters:
- removed: Whether the content margins should be removed.
method · iOS 16.0+
customizationBehavior
Swift declaration
nonisolated func customizationBehavior(_ behavior: ToolbarCustomizationBehavior) -> some CustomizableToolbarContent
Configures the customization behavior of customizable toolbar content.
Customizable toolbar items support different kinds of customization:
* A user can add an item that is not in the toolbar.
* A user can remove an item that is in the toolbar.
* A user can move an item within the toolbar.
Based on the customization behavior of the toolbar items, different
edits will be supported.
Use this modifier to the customization behavior a user can
perform on your toolbar items. In the following example, the
customizable toolbar item supports all of the different kinds of
toolbar customizations and starts in the toolbar.
ContentView()
.toolbar(id: "main") {
ToolbarItem(id: "new") {
// new button here
}
}
You can create an item that can not be removed from the toolbar
or moved within the toolbar by passing a value of
``ToolbarCustomizationBehavior/disabled`` to this modifier.
ContentView()
.toolbar(id: "main") {
ToolbarItem(id: "new") {
// new button here
}
.customizationBehavior(.disabled)
}
You can create an item that can not be removed from the toolbar, but
can be moved by passing a value of
``ToolbarCustomizationBehavior/reorderable``.
ContentView()
.toolbar(id: "main") {
ToolbarItem(id: "new") {
// new button here
}
.customizationBehavior(.reorderable)
}
- Parameter behavior: The customization behavior of the customizable
toolbar content.
method · iOS 26.0+
matchedTransitionSource
Swift declaration
nonisolated func matchedTransitionSource(id: some Hashable, in namespace: Namespace.ID) -> some CustomizableToolbarContent
Identifies this toolbar content as the source of a navigation
transition, such as a zoom transition.
Use this modifier in conjunction with ``View.navigationTransition(_:)``
to provide a source for the transition effect:
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))
}
}
}
}
- Parameters:
- id: The identifier, often derived from the identifier of
the data being displayed by the toolbar content.
- namespace: The namespace in which defines the `id`. New
namespaces are created by adding an ``Namespace`` variable
to a ``View`` or ``ToolbarContent` type and reading its value in
the type's body method.
method · iOS 26.0+
sharedBackgroundVisibility
Swift declaration
nonisolated func sharedBackgroundVisibility(_ visibility: Visibility) -> some CustomizableToolbarContent
Controls the visibility of the glass background effect on items
in the toolbar. In certain contexts, such as the navigation bar
on iOS and the window toolbar on macOS, toolbar items will be
given a glass background effect that is shared with other items
in the same logical grouping.
This modifier adjusts the visibility of that effect. Hiding the
effect will cause the item to be placed in its own grouping.
ContentView()
.toolbar(id: "main") {
ToolbarItem(id: "build-status", placement: principal) {
BuildStatus()
}
.sharedBackgroundVisibility(.hidden)
}
- Parameter visibility: The visibility of the background effect.
