Skip to main content
type ToolbarItemPlacement =
  // Semantic placements
  | "automatic"
  | "principal"
  | "navigation"
  | "primaryAction"
  | "secondaryAction"
  | "status"
  | "confirmationAction"
  | "cancellationAction"
  | "destructiveAction"
  // Positional placements
  | "bottomBar"
  | "topBarLeading"
  | "topBarTrailing"
  | "navigationBarLeading"
  | "navigationBarTrailing"
  | "bottomOrnament"
  | "keyboard"
  | "largeSubtitle"
  | "subtitle"
  | "title";

​
Values

​
Semantic Placements

​
automatic
string
Automatically determines the appropriate placement based on the item’s semantic role and platform conventions.
​
principal
string
The principal or primary item. Typically placed in the center of the navigation bar or toolbar.
​
navigation
string
Navigation-related items. Usually placed in the leading area of the navigation bar.
​
primaryAction
string
The primary action for the current context. Typically placed in a prominent position like the trailing edge.
​
secondaryAction
string
Secondary actions. Placed in less prominent positions than primary actions.
​
status
string
Status information displays. Often placed in the center or a visible location.
​
confirmationAction
string
Confirmation actions like “Save” or “Done”. Typically placed in the trailing edge.
​
cancellationAction
string
Cancellation actions like “Cancel”. Typically placed in the leading edge.
​
destructiveAction
string
Destructive actions like “Delete”. Usually styled differently and placed carefully to prevent accidental activation.

​
Positional Placements

​
bottomBar
string
Places the item in a bottom toolbar or bar.
​
topBarLeading
string
Places the item in the leading (left in LTR) side of the top bar.
​
topBarTrailing
string
Places the item in the trailing (right in LTR) side of the top bar.
​
navigationBarLeading
string
Places the item in the leading side of the navigation bar.
​
navigationBarTrailing
string
Places the item in the trailing side of the navigation bar.
​
bottomOrnament
string
Places the item as a bottom ornament, typically in specialized interfaces like visionOS.
​
keyboard
string
Places the item in an accessory bar above the keyboard.
​
largeSubtitle
string
Places the item as a large subtitle in the navigation bar.
​
subtitle
string
Places the item as a subtitle in the navigation bar.
​
title
string
Places the item in the title area of the navigation bar.

​
Usage

VStack([
  Text("Content")
])
.toolbar([
  // Leading cancel button
  ToolbarItem({ placement: "cancellationAction" }, [
    Button("Cancel", () => { /* ... */ })
  ]),

  // Trailing save button
  ToolbarItem({ placement: "confirmationAction" }, [
    Button("Save", () => { /* ... */ })
  ]),

  // Principal/centered title
  ToolbarItem({ placement: "principal" }, [
    Text("Document Title")
  ])
])

// Multiple items in a group
VStack([
  Text("Content")
])
.toolbar([
  ToolbarItemGroup({ placement: "navigationBarTrailing" }, [
    Button("Edit", () => { /* ... */ }),
    Button("Share", () => { /* ... */ })
  ])
])

​
Platform Considerations

  • Placement behavior may vary by platform (iOS, macOS, web, visionOS)
  • Some placements are platform-specific (e.g., bottomOrnament for visionOS)
  • Semantic placements (automatic, primaryAction, etc.) adapt to platform conventions automatically
  • Positional placements give more control but may not adapt as well across platforms