When to use buttons
Use buttons to:
- Trigger actions on the current page, such as submitting forms or opening modals
- Perform operations like saving, deleting, or editing content
- Control interactive elements like accordions or dialogs
- Confirm or cancel actions in dialogs or workflows
Do not use buttons when:
- Navigating to a new page or URL — use links instead
- Displaying non-interactive text or labels — use text or badges instead
- Showing status information — use badges or alerts instead
Button variants
Three button variants are available in the suite. Some have specific uses:
- Button variants should be used in particular combinations of button groups
- The background surface varies based on the background colour upon which they are placed
- Refer to the button groups documentation for correct variant combinations
Button groups
Button groups are layouts of buttons that convey actions and choices to the user. Consistent layouts and formations across an application improve user familiarity.
The groupings below are the most common.
The following examples feature small viewport buttons stacked vertically, but they can also be displayed horizontally on small viewports when it makes sense for the context or when space allows.
Orientation
Button groups can be displayed vertically or horizontally. The horizontal orientation is more common on screens above the medium breakpoint. However, horizontal orientation has some use cases on smaller screens, particularly nested inside cards.
The primary action should always be placed first in a vertical stack or to the right in a horizontal button group. As additional buttons are added to the group, they are positioned based on importance.
Spacing
Vertical Groups
Button groups with three buttons have a key difference in that the tertiary buttons are double-spaced when vertically stacked. This is to create a clear separation of actions and avoid user error.
Example of vertically stacked buttons
Horizontal Groups
When buttons are placed in groups with all three buttons, the spacing differs slightly.
Spacing in button groups with three buttons illustrated
Grouping Examples
Single Action
The simplest button group. In most cases, this will be the primary action; however, there will be instances where other button styles make sense based on content.
Primary button group example
Primary + Secondary
These actions are usually closely related and are grouped in horizontal and vertically stacked layouts.
Primary & secondary button group example
Secondary Pair
Secondary pairs can be used when the key actions have equal weighting.
Secondary button group example
Primary + Cancel
To reduce any accidental cancellation, the cancel button is placed away from the primary action in the horizontal layout.
Primary and tertiary buttons group example
Primary, Secondary + Delete/Cancel
Following the patterns above, the primary and secondary related actions are grouped, and delete or cancel is outside the grouping. In stacked layouts, the spacing is doubled to create additional whitespace.
Primary & secondary, and tertiary buttons are used for the destructive delete action
Primary & secondary, and tertiary buttons are used for the destructive cancel action
Constructive + Destructive
This button group builds on the same logic as the primary and secondary examples, but with the appropriate button styles.
Primary and tertiary buttons group example
Constructive, Destructive + Cancel
The grouping follows on from the above, making sure that actions are clearly separated by whitespace.
Primary, secondary and tertiary button group example
Next + Back
The primary and secondary buttons are positioned side by side. Next should be closest to the content when stacked vertically and to the left edge when horizontal.
Primary and secondary buttons group example
Additional Button Groups
Pairing examples
Option Buttons
If a user is given one or more options of equal importance, the same style should be used. The style can vary based on the context of the decision. Button groups should be used as a reference.
Pairing
Pairing buttons and using a combination of styles indicates that there are differences in action or intent. Ghost buttons paired with a primary can provide options but display intent.