Guidelines
When to use
- To trigger actions: Use Button for actions that allow users to interact with the page, like submitting forms, creating an entity, confirming choices, canceling, opening filters, etc.
When not to use
- Navigation: Do not use buttons to navigate between pages. Use Links instead.
- Form controls: Do not use buttons to replace form fields, such as Select, Number Input, etc.
Best Practices
- One Primary Button per screen: As a general rule, a page should have only one Primary Button, making it clear that other buttons have less importance in the hierarchy.
Use only one Primary Button.
Don't use two Primary Buttons together.
Button variants
- Primary: A Primary Button is used for the most important action of the page. Only one Primaty Button should be visible on the screen to keep visual balance and avoid overwhelming the user.
- Secondary: Secondary Buttons are typically used for additional actions, complementing a group that already includes a Primary and a Tertiary Button, such as the Export action on Side Panels.
- Tertiary: Tertiary Buttons have a more subtle design and are ideal for pairing together without cluttering the layout. They can be used multiple times in scenarios like Page Headers or alongside other Button variants. They are commonly used to complement the Primary Button, like canceling actions in Dialogs.
- Ghost: Ghost Buttons have no fill or outline. They are best used for subtle actions that generate minimal visual noise. Use with caution, as sometimes they may not be perceived as buttons, which can affect accessibility.
- Destructive: Destructive Buttons represent critical actions, such as deleting or removing content. They're typically used in Dialogs for irreversible confirmations.
Combining variants
Variant names were defined based on style, not usage. This means that grouping buttons won’t follow their naming convention.
A general rule is to pair a high-emphasis button with a lower-emphasis button. Typically, it means combining a Primary Button with the Tertiary variant. Secondary Buttons, while less prominent than the Primary, use accent colors that can be visually heavy, so they are not the first variant choice of pairing different Buttons.
Common combinations
- Multiple actions: In layouts requiring multiple actions, such as page headers, data lists, or dashboards, it’s best to group low-emphasis buttons together to maintain visual balance. For such cases, we usually use Tertiary Buttons.
- Dialogs and Panels: Use a Primary Button for confirmation and a Tertiary Button for actions like canceling or going back. Secondary Buttons should only be used when an extra action is necessary, such as Export.
Combine the same variant of a low-empashis button when multiple actions are needed.
The Tertiary variant is the preferred option when combining a Primary Button with another Button.
Sizes
The Medium variant is the default size for desktop screens, and the Extra Large is used for touch devices.
- Small: Ideal for dense UIs with a lot of content and actions, such as Table actions.
- Medium: The default size for most desktop actions, commonly used in Dialogs, Panel footers, Page Headers, Forms confirmation, etc.
- Large: Best for layouts that require more space. Also used for touch devices like tablets.
- Extra Large: Primarily used for mobile screens, offering the largest touch area for improved accessibility.
Position
The position of a button depends on its context and whether it’s contained within another component or element.
Full Page
The Primary Button is typically aligned to the left when used alone on full-page designs. This positioning aligns with the user’s natural reading direction, making it the focal point, especially on larger screens.
Within an Element
When part of a composition or component, the Primary Button is usually aligned to the right, like in Page Headers, Dialogs, Cards, Progress Indicators, and Data Tables.
When paired with a Tertiary Button (for actions like canceling or going back), the Tertiary Button is typically aligned to the left. This is common in elements such as Side Panels, Dialogs, and Page Footers.
Icons
An optional Icon property is available to add context and help users understand the button's action. To use an icon, enable the Start Icon option. The End Icon should only be used on Dropdown Buttons.
Use the Start Icon to emphasise the button's content.
Don't use the End Icon on regular buttons.
Content
Buttons or CTA’s (calls to action) should be as short and scannable as possible, generally using no more than three words. Avoid the use of articles, when possible, to enable users to act quicker by reducing cognitive load.
Tone
Use an actionable tone when writing content for buttons – start with a verb. Users should know exactly what happens when they interact with any button. Never use a passive tone.
Do
- Clearly explain the action users will take when selecting the button.
- In dialogs, repeat words used in the dialog title and the primary CTA. This will help guide the user to follow through with their intended action.
- Keep texts at three words or less.
- Use sentence case.
Do not
- Initiate more than one action.
- Be ambiguous.
- Include punctuation.
- Use special characters.
Accessibility
Do not mix the usage of buttons and links
Follow the guidance above regarding when to use each. Remember buttons are for triggering actions, not navigating. Misuse causes confusion for keyboard and screen reader users, who may hear them announced by the wrong role.
Make sure button labels are unique and descriptive
Labels like “Click Here” and “Read More” don’t provide context. In addition, some screen reader users also navigate through a list of all the buttons on a page or screen. Therefore, all button labels should provide an indication of what will happen if activated. For examples of acceptable labels, see the content standards section on this page.
WCAG 2.1: 1.3.1 Info and Relationships
Icon-only buttons should be used carefully and only after checking for accessibility
The meaning of the icon must be visually self-evident (easily and universally understood). In addition, a programmatically associated semantic label (such as an aria-label attribute) should be added so it can be read by screen readers. If you’re in any doubt that an icon-only button will be understood, use accompanying text in your button label.
WCAG 2.1: 1.3.1 Info and Relationships
All buttons except tertiary should have a contrast ratio of 3:1 or greater against the background, regardless of breakpoint or orientation (except if inactive)
Providing good contrast ratio on buttons ensures that anyone with low vision can see them and perceive their function. If the button variant doesn’t achieve adequate contrast with the background when viewed at a specific breakpoint, and/or in a particular orientation, either change the background or consider using a different button variant. The tertiary button is an exception and should have a 4.5:1 contrast with its background at all times.
WCAG 2.1: 1.4.11 Non-text Contrast
Tertiary buttons require a 4.5:1 contrast ratio against the background
Greater contrast is required because the text is the only part of the button that is visible. These buttons are therefore considered similar to text and will require a higher contrast ratio.
WCAG 2.1: 1.4.3 Contrast (Minimum), 1.4.11 Non-text Contrast
When possible, use medium or large variant buttons, rather than small
Small buttons (24-pixel height) meet the minimum touch target requirements to ensure adequate accessibility for people with fine motor control difficulties or limited dexterity. Medium buttons (40-pixel height) are much closer to the recommended size of 44px-by-44px, and large buttons (48-pixel height) exceed it. The easier touch targets these larger sizes present for are therefore preferable.
WCAG 2.2 (Proposed): 2.5.8 Target Size (Minimum)
ARIA attributes
- Include alternative text using the <aria-label> prop when using icon buttons.
- When using an icon alongside text, do not add a label to the icon. Doing so will unnecessarily repeat labels for people using screen readers.
- Avoid using disabled buttons, especially in forms. Disabled buttons don't explain why the button isn't usable, and they aren't visible to people using keyboard navigation. Instead, keep the button pressable, using validation and errors to explain what needs to be done to continue.
Resources
WCAG 2.1 Guidelines
1.1.1 Non-text Content - All non-text content that is presented to the user has a text alternative that serves the equivalent purpose (some exceptions). (Level A)
Note: If non-text content is pure decoration, is used only for visual formatting, or is not presented to users, then it does not need text alternatives.