Toolbar Buttons

A toolbar button lets you offer important app functionality in a view that displays related content. Located at the top of a scrolling view, a toolbar button can stay hidden behind the navigation bar until people reveal it by scrolling up.

Screenshot of the Messages app, showing three messages of which the first two are unread.

Screenshot of the Messages app, showing two unread messages below a blue New Message button.

Toolbar buttons are available in watchOS 7 and later; for developer guidance, see ToolbarItemPlacement.primaryAction.

Place a toolbar button only in a scrolling view. People frequently scroll to the top of a scrolling view, so discovering a toolbar button is almost automatic. Placing a toolbar button in a nonscrolling view makes it permanently visible, eliminating the advantage of hiding it when it’s not needed.

Use a toolbar button for an important action that isn’t a primary app function. A toolbar button gives you the flexibility to offer important functionality in a view whose primary purpose is related to that functionality, but may not be the same. For example, Mail provides the essential New Message action in a toolbar button at the top of the Inbox view. The primary purpose of the Inbox is to display a scrollable list of email messages, so it makes sense to offer the closely related compose action in a toolbar button at the top of the view.

Prefer a single, full-width toolbar button. Displaying multiple toolbar buttons — whether stacked or side by side — can complicate the view and require people to make sure they’ve discovered the full set of actions before making a choice. If you’re considering more than one toolbar button, also consider whether your app needs a separate view to enable these essential actions.