How it works
ToolbarCustomizationBehavior describes how an individual toolbar item participates in user customization of a toolbar. When a toolbar is customizable, people can show, hide, and rearrange its items; this type lets you opt a given item into or out of that experience so that essential controls stay fixed while optional ones can be moved or removed. Reach for it when you build an identified, customizable toolbar and need fine-grained control over which items the customization editor is allowed to touch.
Apply the behavior with toolbarCustomizationBehavior(_:)
The behavior is set on the content of a toolbar item through the toolbarCustomizationBehavior(_:) modifier, which takes a single ToolbarCustomizationBehavior value. In the example each Button declares its own behavior, so the modifier scopes the rule to exactly that item rather than the toolbar as a whole.
Lock an item in place with .disabled
The .disabled value excludes the item from customization entirely: it cannot be hidden, removed, or reordered, and it always appears. Here the add Button uses .toolbarCustomizationBehavior(.disabled) so the primary
plusaction remains a permanent fixture of the toolbar.Allow rearranging with .reorderable
The .reorderable value keeps an item present but lets people change its position during customization. The share Button applies .toolbarCustomizationBehavior(.reorderable) to its
square.and.arrow.upcontrol, signaling that this secondary action may be moved but stays part of the toolbar.Tie behaviors to an identified toolbar
Customization behaviors only take effect within a customizable toolbar, which is one declared with an identifier and items that carry their own ids. The behaviors above live inside .toolbar(id: "main") whose ToolbarItem entries are keyed "add" and "share", giving SwiftUI the stable identity it needs to persist each item's customization state.
plus item become draggable.Example & preview
Press Run live & edit to compile it in your browser — then edit the Swift on the left and the preview re-renders live.
struct ToolbarCustomizationBehaviorDemo: View {
var body: some View {
NavigationStack {
Text("Edit the toolbar")
.padding()
.toolbar(id: "main") {
ToolbarItem(id: "add", placement: .primaryAction) {
Button {
} label: {
Image(systemName: "plus")
}
.toolbarCustomizationBehavior(.disabled)
}
ToolbarItem(id: "share", placement: .secondaryAction) {
Button {
} label: {
Image(systemName: "square.and.arrow.up")
}
.toolbarCustomizationBehavior(.reorderable)
}
}
.toolbarRole(.editor)
}
}
}