Skip to main content

Button

Last updated:
2/12/2024

A button allows the user to take an action or trigger an event.

View in Storybook

Modifiers

Button with icon on the left

Use a button with an icon on the left if the button’s action requires an accompanying icon. Putting the icon first allows the user to scan the icon and the text faster. Use a button with the icon on the left for most actions that won’t move the user forward or take the user to another location.

Button with icon on the right

Use a button with an icon on the right if the button’s action requires an accompanying icon and if the action moves the user forward or takes the user to another location. One example of this would be a call-to-action.

Icon

Use the icon button if the action is completely obvious, like going to the next page in a pagination component or scrolling within tabs.

Styles

Default

Use the default style when the action is not the primary action on the page.

Assertive

Use the assertive style when the action is the primary action on the page. There should be only one assertive action on the page because there should be only one primary action per page.

Ghost

Use the ghost style when the action is on a dark background. Make sure that the button passes accessibility requirements of AA, and AAA when possible.

Subtle

Use the subtle style to de-emphasize the action.

Text button

Use the text button style for situations where other buttons may be distracting, for actions that are low-priority, or if the action needs to be left aligned with related content. This style does not support icon-only buttons.

Active filter button

Active filter buttons show selected filters. Use active filter buttons as part of a filtering pattern.

States

Disabled

Use the disabled state only when necessary. Disabled buttons do not have to pass contrast requirements and can be confusing. If you need to disable a button, make sure the reason is obvious. If the reason is not obvious, you can keep the button enabled and add an error message to explain.

Usage

Button sizes

There are two button sizes: default and small.

The default button size is the most common and should be used in most situations.

Only use small buttons when there is a need for vertical density or if the action should be de-emphasized. Small buttons should be true actions, not a calls-to-action (links). The small size is only available for the default, subtle, and ghost styles. Small buttons should not be used for primary actions or for icon-only actions.

Do:

  • Use buttons for actions
  • Use an assertive button to draw attention to the primary action on the page
  • Only use ghost buttons on dark backgrounds that pass at least AA standards and AAA when possible
  • Use the small size only when you need to save vertical space or to minimize the action
  • Use text buttons for low-priority actions
  • Use active filter buttons as part of a filtering pattern

Don't:

  • Use buttons to take a user to a location — use a link instead
  • Use more than one assertive button on the page
  • Use small buttons or text buttons for calls-to-action
  • Use small buttons or text buttons for primary actions
  • Use small buttons or text buttons for icon-only actions
  • Use active filter buttons for anything other than within a filtering pattern

Content guidelines

For more information, refer to the Buttons section in Content guidelines.

Do:

  • Lead with a verb in the button text
  • Use unique, concise, and easily understood button text
  • Use sentence case
  • Use icons sparingly and with purpose
  • If invisible text is necessary, append it to the end of the button text
  • Keep the back button text as simple as possible
  • Use sentence case, except for proper nouns and product names

Don't:

  • Use title case or all caps
  • Use long or redundant button text
  • Use vague or generic button text
  • Use icons as decoration
  • Add invisible text in the middle of button text
  • Remove the word “Back” in navigation back buttons
  • Don’t add non-essential words

Accessibility

This component passes AAA WCAG standards. However, changes made by the content owner or implementer could impact accessibility compliance. Be sure to follow code standards and content guidelines to ensure that this component is fully accessible.

For more information, see WAI-ARIA Authoring Practices for buttons and Deque’s screen reader keyboard shortcuts and gestures documentation.