Button - CMS Design System

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.

Button variations on light background
Variation	Main (Default)	Alternate
Outline (Default)
Solid
Ghost

Button variations on dark background
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 viewBox with values that are multiples of 8 (ie. 24x24).
Use the margin utility class to add spacing between the icon and button text.

<div>
  <button type="button" class="ds-c-button ds-u-margin-right--1">
    <svg
      aria-hidden="true"
      class="ds-c-icon ds-c-icon--arrow ds-c-icon--arrow-left ds-u-margin-right--05"
      focusable="false"
      id="icon-2058"
      viewBox="0 0 320 512"
      xmlns="http://www.w3.org/2000/svg"
      direction="left"
    >
      <path
        fill="currentColor"
        d="M285.476 272.971L91.132 467.314c-9.373 9.373-24.569 9.373-33.941 0l-22.667-22.667c-9.357-9.357-9.375-24.522-.04-33.901L188.505 256 34.484 101.255c-9.335-9.379-9.317-24.544.04-33.901l22.667-22.667c9.373-9.373 24.569-9.373 33.941 0L285.475 239.03c9.373 9.372 9.373 24.568.001 33.941z"
      ></path>
    </svg>
    Left Icon
  </button>
  <button type="button" class="ds-c-button ds-u-margin-right--1">
    Right Icon
    <svg
      aria-hidden="true"
      class="ds-c-icon ds-c-icon--arrow ds-c-icon--arrow-right ds-u-margin-left--05"
      focusable="false"
      id="icon-2059"
      viewBox="0 0 320 512"
      xmlns="http://www.w3.org/2000/svg"
      direction="right"
    >
      <path
        fill="currentColor"
        d="M285.476 272.971L91.132 467.314c-9.373 9.373-24.569 9.373-33.941 0l-22.667-22.667c-9.357-9.357-9.375-24.522-.04-33.901L188.505 256 34.484 101.255c-9.335-9.379-9.317-24.544.04-33.901l22.667-22.667c9.373-9.373 24.569-9.373 33.941 0L285.475 239.03c9.373 9.372 9.373 24.568.001 33.941z"
      ></path>
    </svg>
  </button>
</div>

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.

React Properties Documentation
Name	Type	Default	Description
`children`required	`ReactNode`		Label text or HTML
`className`	`string`		Additional classes to be added to the root button element.
`disabled`	`boolean`
`href`	`string`		When provided, the root component will render as an `<a>` element rather than `button`.
`inputRef`	`ButtonRef`		Access a reference to the `button` or `a` element
`isAlternate`	`boolean`	`false`	Applies the alternate color to a Button. By default, Button uses the `main` color.
`onClick`	`(...args: any[]) => any`		Returns the `SyntheticEvent`. Not called when the Button is disabled.
`onDark`	`boolean`	`false`	Defines a color palette best used when Button is placed on a dark background-color. By default, Button uses a light color palette.
`size`	`ButtonSize`
`type`	`"button" \| "submit" \| "reset"`	`'button' as const`	Button `type` attribute
`variation`	`ButtonVariation`		A string corresponding to Button variation classes.
`analytics`	`boolean`		Analytics events tracking is enabled by default. Set this value to `false` to disable tracking for this component instance.
`analyticsLabelOverride`	`string`		An override for the dynamic content sent to analytics services. By default this content comes from the heading. In cases where this component’s heading may contain sensitive information, use this prop to override what is sent to analytics.
`analyticsEventTypeOverride`	`string`		If you need the `event_type` to be overridden for your use case, you can provide an alternate string here. Suggested values can be found in the EventType enum.
`onAnalyticsEvent`	`(event: AnalyticsEvent) => void`		Optional callback that will intercept analytics events for this component. If none is specified, the design system will use the default analytics function, which can be overwritten globally with `setDefaultAnalyticsFunction`.
`analyticsParentHeading`	`string`		If needed for analytics, pass heading text of parent component of button.
`analyticsParentType`	`string`		If needed for analytics, pass type of parent component of button.
This component passes any additional props to its underlying `<button>` or `<a>` element as attributes. See the corresponding MDN documentation for `<button>` and `<a>` for a list of valid attributes.

Styles

The following CSS variables can be overridden to customize Button components:

CSS variables for button
Variable	Default Core Theme Value
`--button__background-color--active`	`--color-border`
`--button__background-color--disabled`	`transparent`
`--button__background-color--hover`	`--color-gray-lightest`
`--button__background-color`	`transparent`
`--button__border-color--active`	`currentColor`
`--button__border-color--disabled`	`currentColor`
`--button__border-color--hover`	`currentColor`
`--button__border-color`	`currentColor`
`--button__border-radius`	`3px`
`--button__border-width`	`1px`
`--button__color--active`	`--color-background-inverse`
`--button__color--disabled`	`--color-border`
`--button__color--hover`	`--color-primary-darker`
`--button__color`	`--color-primary`
`--button__font-weight`	`700`
`--button-icon__fill`	`currentColor`

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.

Avoid using disabled buttons

Disabling a "button" to act as a guide to the level of form completion is a common anti-pattern (e.g., you aren't able to proceed in the next step until the form contains enough data). Why it's a problem:

Buttons tend to have call-to-action text that matches what users want to do, so people try to interact with them.
They have terrible color contrast.
They don’t provide feedback and tell the user why they're disabled. They communicate that something is off, but very often that is not enough information. As a result, users are left wondering what’s actually missing, and consequently are locked out entirely.
Assistive technologies like screen readers and switches are usually not even able to navigate to disabled buttons.

For these reasons, disabled buttons can be frustrating for all users but especially those with cognitive disabilities and those who use assistive technologies.

Accessibility

Buttons should display a visible focus state when users tab to them.
Create a button with a <button> or <a> element to retain the native click functionality. Avoid using <div> or <img> tags to create buttons. Screen readers don't automatically know either is a usable button.
When styling links to look like buttons, remember that screen readers handle links slightly differently than they do buttons. Pressing the Space key triggers a button, but pressing the Enter key triggers a link.
Dimmed or unavailable buttons using the <a> tag must have the aria-disabled attribute set to true and its href attribute removed.
- Unlike the <button>, disabled is not a valid attribute for <a>. To describe the disabled state to screen reader users, use the aria-disabled attribute instead.
- The href attribute is not required on <a>, and when it's absent it doesn't create a hyperlink.
Dimmed or 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.

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

Button alignment

ARIA

Component maturity

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.

Accessibility

Color
Meets AA color contrast standards for accessibility and color blindness.
Complete
Forced Colors Mode (FCM)
While using FCM the components text is legible and improves readability.
Complete
WCAG 2.1 Level AA Conformance
All Axe checks for WCAG AA compliance have passed.
Complete
Screen readers
VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
Complete
Keyboard navigation
Component is fully navigable with a keyboard.
Complete

Code

Storybook
Component has stories to cover all defined props.
Complete
Responsive
Component designed to work in all responsive breakpoints.
Complete
Spanish translations
Includes Spanish translations for default text content.
Not applicable

Tokens

Code
Tokens implemented in code.
Complete
Design
Tokens implemented in the Sketch.
Complete

On this pageOpen

Have ideas?

Are you upgrading to v4 (healthcare v8, medicare v6)?

Examples

Main buttons

Solid button

Outline button

Ghost button

Alternate buttons

Alternate solid button

Alternate outline button

Alternate ghost button

On dark background

Button sizes

Big button

Small button

Adding icons

Code

React

Styles

Analytics

Guidance

When to use

When to consider alternatives

Usage

Accessibility

Content

Moving through a process or sequential steps after starting

Learn more

Component maturity

Accessibility

Color

Forced Colors Mode (FCM)

WCAG 2.1 Level AA Conformance

Screen readers

Keyboard navigation

Code

Storybook

Responsive

Spanish translations

Tokens

Code

Design

On this page

Have ideas?