Figma
StorybookAre you upgrading to v4 (healthcare v8, medicare v6)?
Take a look at our v4 buttons migration guide to get started.
Examples
The following tables give an overview of the different available button styles in the selected design system. Each button has three controllable traits that can be used in various combinations. They are:
- Variation: which affects the border and background styles
- Color: defined as either main or alternate
- Context: specified as either on-light or on-dark
See the examples in the following sections to learn how they can be applied.
| Variation | Main (Default) | Alternate |
|---|---|---|
| Outline (Default) | ||
| Solid | ||
| Ghost |
| Variation | Main (Default) | Alternate |
|---|---|---|
| Outline (Default) | ||
| Solid | ||
| Ghost |
Main buttons
Solid button
Outline button
Ghost button
Alternate buttons
Each button variation (outline, solid, ghost) has an alternate option. Alternate buttons can be styled differently than the main buttons.
Alternate solid button
Alternate outline button
Alternate ghost button
On dark background
Button sizes
Buttons can exist in two sizes other than default: "big" or "small".
Big button
Small button
Adding icons
- Add an inline SVG icon and it will become the same color as the button text. For the crispest icon rendering, ensure the icon has a square
viewBoxwith values that are multiples of8(ie.24x24). - Use the margin utility class to add spacing between the icon and button text.
Code
React
The Button component accepts its text as children (AKA inner HTML), which
means you can also pass in HTML or custom components. This gives you a lot of
flexibility and supports a variety of advanced use cases. The most common use
case would be passing in an SVG icon along with the text.
In addition to the supported props listed, you can also pass in additional
props, which will be passed to the rendered root component. For example,
you could pass in a target prop to pass to the rendered anchor element.
Review Storybook for React guidance of this component.
Web Component
Go to Storybook for Web Component guidance of this component.
Style customization
The following CSS variables can be overridden to customize Button components:
Analytics
This component has analytics tracking available. Please see our developer documentation about using analytics in the design system.
Guidance
Buttons are promises to the user; they must deliver the promise they offer by doing what the button says it will do.
When to use
- Use buttons for the most important actions you want users to take on your site, such as "Download," "Sign up," or "Apply."
When to consider alternatives
- Less popular or less important actions may be visually styled as links.
- Buttons are for performing actions, not making choices. If you need your users to make a choice, use something else like radio buttons. Alternatively, if one choice is much less important then try styling it as a link instead.
Usage
- Avoid using too many buttons on a page. Aim to use only one button per page.
- Avoid similar styles elsewhere on the page that could be confused for buttons.
- Use buttons for the primary action and links for secondary actions.
Label text
- Use sentence case for button labels.
- Button labels should be as short as possible with “trigger words” that your users will recognize to clearly explain what will happen when the button is clicked (for example, “Save and continue,” “Download” or “Sign up”).
- Make the first word of the button’s label a verb. For example, instead of “Complaint Filing”, label the button “File a complaint.”
- If a button has an icon, it should still have accompanying text describing the action.
Destructive buttons
- Confirm the user meant to trigger a destructive action before following through with the action.
- Provide a method for a user to undo a destructive action.
Accessibility
- Make sure the
typeattribute has the correct value. By default, this is set tosubmitbut in most you’ll need to set this tobuttonto prevent unwanted behavior when pressed.
Links vs. buttons
Links and buttons are read differently when using a screen reader. In its most basic form, the rules are:
- If it goes somewhere, use a link in the form of
<a>. - If it does something on the page such as submitting a form, opening a dialog, canceling an action, or deleting an item, then use a button in the form of
<button>.
Navigating with a screen reader
Web browsers and assistive technology aid users by providing lists of common elements like headings, buttons, links, and images, and let you navigate directly to the element of your choosing. This allows screen reader users to speed up their comprehension of the page.
One example of this collection of lists in a screen reader is the VoiceOver rotor on a Mac. To turn on VoiceOver’s rotor, use the keyboard shortcut: control + alt + U.
If elements are not coded semantically (a link as a button or a button as a link), then users won't be able to navigate a page as easily.
Navigating with a keyboard
For users who navigate pages with keyboards instead of a mouse, buttons can be triggered by pressing the space bar or the enter key while links are only triggered by the enter key. This makes a difference to a screen reader user's flow.
Icon buttons
An element's name, or accessible name, is how it is identified by browsers and the accessibility tree. Accessible names provide information for assistive technology, such as screen readers, and so icon buttons must include an accessible name. If there is no text beside the icon then an aria-label or aria-labelledby attribute can be used to give the button its accessible name.
Size
The click/tap target area must be no smaller than 44x44px.
Avoid using disabled buttons
Disabling or making a "button" unavailable until a form or input field is complete can confuse some users.
Why it's a problem:
- They don’t provide feedback and tell the user why they're disabled. They communicate that something isn’t right, but very often that is not enough information.
- Buttons should have call-to-action text that matches what users want to do, so people try to interact with them yet they aren’t able to be interacted with.
- They typically have terrible color contrast.
- Assistive technologies like screen readers and switches are usually not able to navigate to disabled buttons.
For these reasons, disabled buttons can be frustrating for all users but especially to those with cognitive disabilities and those who use assistive technologies.
If you have a use case where you must use a disabled button, take note:
- If using the
<a>tag- Add
aria-disabledattribute set to true as this helps to describe the disabled state to screen reader users. - Remove its
hrefattribute. When a link has nohref, it has no role, no focusability, and no keyboard events. - Do not use the disabled attribute as it is not a valid attribute for
<a>.
- Add
Unavailable buttons using the <button> tag should have the disabled attribute applied. This removes native click and keypress events from the button. It also prevents automated scanners from logging a low contrast error. Finally, it announces the button as "dimmed" or "disabled" to screen readers, offering users additional context.
State
If a toggle-able button is needed, add aria-pressed to the button. Examples of this use case could be: buttons to change settings, buttons to sort with, etc.
Accessibility testing
General
- The click/tap target area is no smaller than 44x44px.
- There is a visible focus state.
Keyboard
- The spacebar and/or enter key are used to activate the button.
- Buttons should display a visible focus state when users tab to them.
Screen reader
Desktop
When I navigate to the button:
- Its purpose and/or resulting action is read.
- The text content within the button is clear as to what it does.
- If applicable, the state (for example: pressed, expanded, etc.) is is read.
Mobile
When I swipe to focus on a button:
- Its purpose and/or resulting action is read.
- The text content within the button is clear as to what it does.
- If applicable, the state (for example: pressed, expanded, etc.) is is read.
Content
- Describe what will happen, not the current state.
- Buttons always start with an action word describing the main thing users will do once selected.
- Pair it with a noun to help it be clearer. Example: Get tips.
- If in a form, it can be just the action word if it's navigating between steps. Example: Cancel, Back, Next.
- Use the least amount of words possible (no more than 6 with 2-4 being ideal).
Moving through a process or sequential steps after starting
For forward movement to the next page or step.
Learn more
- Beyond Blue Links: Making Clickable Elements Recognizable
- 7 Basic Best Practices for Buttons
- The Grammar of Interactivity
- GOV.UK navigation buttons discussion
Button alignment
ARIA
Related components
Component maturity
For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.