How it works
ToolbarCustomizationOptions is an option set that tunes how an individual toolbar item participates in user customization. When you build a customizable toolbar with toolbar(id:), people can show, hide, and rearrange its items; these options let you constrain that freedom on a per-item basis. Reach for ToolbarCustomizationOptions when a control must always remain reachable in the customization palette even if the user removes it from the bar, so essential actions can never be permanently lost.
Opt the item into customization with toolbar(id:)
ToolbarCustomizationOptionsonly has an effect inside a toolbar that participates in customization, which you establish by giving the toolbar a stable identifier. Here.toolbar(id: "main")marks the bar as customizable, and eachToolbarItem(id:)inside it carries its own identity ("bold","italic") so the system can persist the user's arrangement.Set the starting state and options with defaultCustomization(_:options:)
The
defaultCustomization(_:options:)modifier declares an item's initial visibility along with aToolbarCustomizationOptionsvalue that governs how it can be customized. In the example,.defaultCustomization(.visible, options: .alwaysAvailable)starts the bold control visible and pins its behavior, while the italic item uses the single-argument form.defaultCustomization(.hidden)to start hidden with default options.Keep an item reachable with alwaysAvailable
The
alwaysAvailableoption is the key member ofToolbarCustomizationOptions: it guarantees the item stays present in the customization experience so the user can always restore it, even after hiding it from the bar. Applying it to the"bold"ToolbarItemensures that core formatting action can be re-added at any time rather than disappearing for good.Combine options as an OptionSet
ToolbarCustomizationOptionsconforms toOptionSet, so you pass either a single option like.alwaysAvailableor a set literal combining several. This is whyoptions:accepts a value type that reads like an enum case at the call site while still supporting unions, letting one declaration express multiple customization constraints at once.Pair with a customization-aware toolbar role
The options take fullest effect when the toolbar presents an editing-style customization affordance, which
.toolbarRole(.editor)requests on theNavigationStackcontent. The role shapes how the customizable bar and its overflow are surfaced, providing the surface where analwaysAvailableitem shows up for the user to manage.
.defaultCustomization(.visible, options: .alwaysAvailable) on the bold item to .defaultCustomization(.hidden, options: .alwaysAvailable) and confirm the bold control starts off the bar yet still appears in the customization palette to be restored.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 ToolbarCustomizationOptionsDemo: View {
var body: some View {
NavigationStack {
Text("Customizable Toolbar")
.padding()
.navigationTitle("Editor")
.toolbar(id: "main") {
ToolbarItem(id: "bold", placement: .secondaryAction) {
Button {
} label: {
Image(systemName: "bold")
}
.defaultCustomization(.visible, options: .alwaysAvailable)
}
ToolbarItem(id: "italic", placement: .secondaryAction) {
Button {
} label: {
Image(systemName: "italic")
}
.defaultCustomization(.hidden)
}
}
.toolbarRole(.editor)
}
}
}