Overview

Button

Buttons are used to initialise actions. They have succinct labels that clearly describe the action that will be triggered.

Button

Usage

When to use
Buttons allow users to take action, such as 'Save', 'Submit', 'Edit', and 'Cancel'. They're typically placed throughout the interface, such as in dialogs, forms, and drawers. To learn more about pairing them, refer to the Button group page.
Button type
Usage
Primary
Primary buttons are the most prominent button on a page. Use them to draw attention to the most important actions on a screen or section, including actions that help users complete a journey, e.g. 'Next', 'Confirm', or 'Submit'.
Secondary
Secondary buttons have a medium level of prominence. They feature actions that are important, but aren't the primary actions in the context of the screen or section. They can be paired with primary buttons to indicate an alternative, secondary action.
Tertiary
Tertiary buttons are the least prominent and are given the lowest emphasis. They're used for supplementary actions that people may find helpful, but likely will not use at the moment. They can be paired with primary buttons to indicate an opposite action, such as 'Cancel' or 'Skip'.
Primary button
Typically, only one primary button is present on a page. However, depending on the context, you can have one primary button per container or per section. Actions related to payment are treated as high priority, so a primary button should be used for payment-related actions.
Single primary button per page
The primary button stands out on the page, guiding users to focus on the task at hand.
Multiple primary buttons per page
You can have multiple primary buttons if there are multiple primary actions that have the same hierarchy on a screen.
Secondary button
Secondary buttons can be used as a standalone or paired with primary buttons. When used as a standalone, make sure the action it represents is secondary compared to the main action of the page or section. For details on paired usage, refer to Button group.
Secondary button use cases.png
Tertiary button
Tertiary buttons are for miscellaneous actions that users may not have an immediate or frequent need for, such as 'Share', 'Sort', and 'Forgot password'. They're not meant for primary actions. Since they're supposed to have the lowest prominence on the page, we apply charcoal colours to these variants to establish a clean hierarchy.
Tertiary with icon
An icon paired with text offers optimal accessibility for different user types. Use as a standalone for CTAs such as 'Download', 'Edit', and 'Print'.
Secondary button use cases.png
Tertiary with underline
The underlined version carries the least visual prominence among all button variants, as it doesn't distract from the nearby content. Always use it with a component, primary action, or paragraph of text, and never as a standalone.
Used within a component
Use this within a range of components. For example, the page-level message component is prominent enough, so using the tertiary with underline achieves good visual balance.
Used with a primary button
Use the tertiary with underline to offer a low-emphasis action or to offer a way out of a decision, such as 'Cancel', 'Skip', or 'Clear'.
Used with a paragraph
Place it at the bottom of a paragraph or block of text as a 'Show more' button that displays more content.
How best to use
Don't
Don't use the tertiary with underline when you can add a hyperlink to the body copy.
Don't
Don't have too many buttons in a container, especially if they're not logically related. Consider placing additional actions in a drawer or dialog, or use icon buttons instead.
Don't
Don't embed an icon within primary or secondary buttons, as the text labels already describe the action or purpose.
Component comparison table
Component
Usage
Placement
Appearance and interactions
Tertiary with underline
Use a tertiary button with underline when you need to trigger an action, such as expanding a content section or cancelling a request.
Usually at the bottom of a paragraph or block of text, never within a paragraph. You can also place it in a component or use it with a primary action.
Charcoal in colour, with 14px top and bottom padding on the button label. This increases the selectable area for better accessibility.
Hyperlinks
Use a hyperlink when navigating the user to a different page, for example when there's a URL change.
Often within a paragraph or a surrounding block of body copy. You can place as many hyperlinks on a page as needed.
Red in its default state for easier identification. They have the same line height as the surrounding text.
Tertiary with underline
Hyperlinks