Reading time: 5 min

This recipe is a cheatsheet for various ToolbarItemPlacement values and combinations on iOS. This is useful because:

1. The namings of the placement values don't necessarily clearly depict where will a ToolbarItem end up.
2. Some values don't play well with each other. E.g, .primaryAction will hide .confirmationAction if it's placed above it, but not if placed below.
3. Some positions change if TitleDisplayMode is .inline.

First we'll quickly introduce the toolbar modifier, and then we'll look at how do various item placements and their combinations look on iOS.

Intro to Toolbars

iOS 14 introduced the toolbar modifier, allowing you to add ToolbarItems to either the toolbar (bottom bar) or the navigation bar. Note that this only works for views that are embedded in a NavigationView (either directly, or become via the navigation stack).

Here's a simple example that adds a few buttons around:

struct ToolbarTestView: View {
  var body: some View {
    NavigationView { // 1
      Text("Hello, World!")
        .padding()
        .navigationTitle("Toolbar Tester")
        .blueNavigation
        .toolbar { // 2
          ToolbarItem(placement: .navigation) { // 3
            Button("Navigation") { } // 4
          }
          ToolbarItem(placement: .bottomBar) { // 3
            Button("BottomBar") { } // 4
          }
        }
    }
  }
}

What happens here is:

1. Views that use toolbar must be embedded in NavigationView. Alternatively, the view from which you navigated to via NavigationLink should be.
2. Use the same toolbar modifier for all items, regardless of if they're in the navigation bar or bottom bar.
3. Use the ToolbarItem wrapper to add items to the bar and specify the position with placement:.
4. Add a regular Button with a title and empty action.

The result looks like this. You can see two buttons, one added to the navigation bar and one to the bottom toolbar:

Okay, time to dive into all the placements and their combos!

ToolbarItemPlacement and its values

The ToolbarItemPlacement is a struct with a bunch of static constants representing different toolbar placements (you can think of it as an enum, even though it's not implemented that way). Here are all the supported placement values:

• automatic
• principal
• navigation
• primaryAction
• status
• confirmationAction
• cancellationAction
• destructiveAction
• navigationBarLeading
• navigationBarTrailing
• bottomBar

We'll look at the placements that affect the bottom space (bottom toolbar) and the top space (navigation bar) separately, as they don't affect each other.

Bottom bar placements

The bottom bar placements are status and bottomBar.

ToolbarItem(placement: ToolbarItemPlacement.status) {
  Button("Status") { }
}
ToolbarItem(placement: ToolbarItemPlacement.bottomBar) {
  Button("BottomBar") { }
}

• status is placed in the center of the toolbar.
• bottomBar starts from the leading edge of the toolbar.

If you add another bottomBar to the list:

ToolbarItem(placement: ToolbarItemPlacement.bottomBar) {
  Button("BottomBar2") { }
}

it goes to the trailing edge:

If you keep adding more bottomBar items:

ToolbarItem(placement: ToolbarItemPlacement.bottomBar) {
  Button("BottomBar3") { }
}

they'll keep lining up at the trailing edge:

Multiple status items:

ToolbarItem(placement: ToolbarItemPlacement.status) {
  Button("Status") { }
}
ToolbarItem(placement: ToolbarItemPlacement.status) {
  Button("Status2") { }
}

are just sequentially lined up in the center (if possible):

ToolbarItem(placement: ToolbarItemPlacement.automatic) {
  Button("Automatic") { }
}
ToolbarItem(placement: ToolbarItemPlacement.principal) {
  Button("Principal") { }
}
ToolbarItem(placement: ToolbarItemPlacement.navigation) {
  Button("Navigation") { }
}

ToolbarItem(placement: ToolbarItemPlacement.automatic) {
  Button("Automatic") { }
}
ToolbarItem(placement: ToolbarItemPlacement.navigationBarTrailing) {
  Button("NavigationBarTrailing") { }
}
ToolbarItem(placement: ToolbarItemPlacement.primaryAction) {
  Button("PrimaryAction") { }
}
ToolbarItem(placement: ToolbarItemPlacement.confirmationAction) {
  Button("ConfirmationAction") { }
}
ToolbarItem(placement: ToolbarItemPlacement.destructiveAction) {
  Button("DestructiveAction") { }
}

ToolbarItem(placement: ToolbarItemPlacement.navigation) {
  Button("Navigation") { }
}
ToolbarItem(placement: ToolbarItemPlacement.cancellationAction) {
  Button("CancellationAction") { }
}
ToolbarItem(placement: ToolbarItemPlacement.navigationBarLeading) {
  Button("NavigationBarLeading") { }
}

ToolbarItem(placement: ToolbarItemPlacement.cancellationAction) {
  Button("CancellationAction") { }
}
ToolbarItem(placement: ToolbarItemPlacement.navigationBarLeading) {
  Button("NavigationBarLeading") { }
}

ToolbarItem(placement: ToolbarItemPlacement.navigation) {
  Button("Navigation") { }
}

.navigationBarTitle("Toolbar Tester", displayMode: .inline)

Next Post Previous Post