Figma
StorybookExamples
There are 3 variations of buttons:
- Solid – Also called a “primary” button.
- Outline – Also called a “secondary” button.
- Ghost – A button without visible outline styling. Ghost buttons appear to look like hyperlinked text, but they have button attributes.
Each button variation is available in a main color and an approved alternate color for both light and dark backgrounds.
| 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 (solid, outline, ghost) has an alternate option.
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
- When adding an inline SVG icon, it will appear in the same color as the button text.
- For the crispest icon rendering, the icon must have a square
viewBoxwith values that are multiples of 8 (e.g., 24x24). - Use the margin utility class to add spacing between the icon and button text.
Paired buttons or multiple buttons on a page
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 to guide users to initiate an action, like “Apply” or “Find plans,” or take the next logical step in their journey or form.
- Be judicious: Buttons are reserved for the most important actions you want users to take on your site.
- Solid/primary button: Use for the primary action you want users to take.
- Outline/secondary button: Use when you have multiple actions available, but it’s not the primary action you want users to take. If there’s no preferred pathway/action, you can use 2 secondary buttons. You don’t have to pair a primary button with a secondary button.
- Ghost button: Use for non-preferred or less common actions, or when you don’t want to draw focus to the action.
- Alternate buttons: Use when there’s more than one button on a page that aren’t paired together and you need to highlight a button that’s not a primary action.
- Big button: Use only for website homepage hero space CTAs that are the start of a user flow or go to multiple pages.
- Small button: Use for:
- Utility actions, like “Print” and “Menu.”
- Tertiary situations, such as inline actions within a step, so users can make changes, like “Edit,” “Remove,” or “Add.” The small button provides the inline action to adjust a particular element on the page, while the primary or secondary buttons take the user to the next step in the form or journey.
- Icons with buttons: Don’t include icons in buttons, except in limited situations:
- Utility actions, like print, email, etc.
- Mobile CTAs for functionality, like filter, sort, map, and menu.
- Branded buttons, like Facebook, Twitter, and YouTube in the website footer.
- Paired buttons:
- Use when there’s 2 clear actions related to each other for a particular action, form, or place in the user journey:
- Form progression: Always include a primary button for preferred action and secondary or ghost button for nonpreferred action. Example: “Next” and “Back”
- Action submission: Always include a primary button for preferred action and secondary or ghost button for nonpreferred action. Example: “Save” and “Cancel”
- User journey or multiple options to take action: Include a primary button for preferred action and secondary button for alternate action. If neither option is preferred, use only secondary buttons. Examples: 1) “Preview plans” and “Apply now” 2) “Log in” and “Create account” 3) “Add,” “Edit,” and “Remove.”
- Positions of paired buttons:
- Forms, decisions trees, or progression of steps: Have the preferred action on the right. Example: “Back” on left and “Next” on right.
- Informational content and other cases: Have the preferred action on the left. Example: “Create account” on left and “Back to home” on right.
- Mobile: Have the preferred action appear before (above) the nonpreferred action.
- Use when there’s 2 clear actions related to each other for a particular action, form, or place in the user journey:
- Multiple buttons on a page: Use sparingly: Use only when you have multiple main pathways or actions for users to take. Can use both standard and alternate styling as needed to differentiate the actions and create visual order to the design.
- Buttons on cards: These are generally links to other pages styled as buttons on the front-end to provide visual importance to help users navigate or continue their journey. When styling links in cards as buttons, use either solid or outline variations. If have more than 1 card on a page, the button styling across the cards needs to match.
- Destructive buttons: Don’t permit users to take a destructive action with a single button.
- When including an action that’s non-reversable once taken, always trigger a new pattern, like a pop-up window or other alert, that explains the ramification and forces the user to re-confirm the destructive action.
- You must include a way for the user to stop the destructive action.
- When providing the options for the destructive action, always have the opt-out or cancel option be the solid button and the destructive action be the outline button.
When to consider alternatives
- Less popular or less important actions may be 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. Too many buttons confuse users and interrupt their willingness to take an action.
- Aim for 1 button per page.
- If you need more than 1 button, consider the user journey and action you want the user to take. Users focus on primary buttons for their next step.
- Avoid similar styles elsewhere on the page that could be confused for buttons.
- Avoid disabled buttons. Buttons that are visible but not usable until all required elements in a form are complete cause user confusion and frustration. Instead, use an active button, but establish error messaging if the form isn’t complete. Refer to error alerts.
Label text
- Aim for 4 words or less.
- No articles or punctuation. Use "&" instead of "and."
- Pronouns:
- Avoid pronouns when going to a page where the user will get generalized information.
- Use first-person pronouns when going to a page with personalized information. Example: “Check if I qualify”
- Use sentence case
- Describe what will happen, not the current state. Example: "Start over"
- Always start with an action verb that describes the main thing users will be able to do once selected.
- Pair the action verb with a noun to help it be clearer. Example: “Preview plans” or “Submit application”
- In forms, use just the action verb when navigating between steps. Examples: “Next,” “Cancel,” “Back,” “Submit”
- In forms and interactive flows, be consistent for steps, and be consistent across tools within the Healthcare, Medicare, or CMS experiences.
- Buttons with icons must include a text label. (Don’t use only the icon as a button.)
Accessibility
General 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>.
Keyboard navigation
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.
Screen reader navigation
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.
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 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.
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. Get developer documentation about using analytics in the design system.
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.