CMS Design System

Use buttons to signal actions.

Default Button

Code snippet

<div>
  <button class="ds-c-button ds-u-margin-right--1" type="button">
    Default
  </button>
  <button
    class="ds-c-button ds-c-button--hover ds-u-margin-right--1"
    type="button"
  >
    Hover
  </button>
  <button
    class="ds-c-button ds-c-button--active ds-u-margin-right--1"
    type="button"
  >
    Active
  </button>
  <button
    class="ds-c-button ds-c-button--focus ds-u-margin-right--1"
    type="button"
  >
    Focus
  </button>
  <button class="ds-c-button" disabled="" type="button">Disabled</button>
</div>

Primary Button

Code snippet

<div>
  <button
    class="ds-c-button ds-c-button--primary ds-u-margin-right--1"
    type="button"
  >
    Default
  </button>
  <button
    class="ds-c-button ds-c-button--primary ds-c-button--hover ds-u-margin-right--1"
    type="button"
  >
    Hover
  </button>
  <button
    class="ds-c-button ds-c-button--primary ds-c-button--active ds-u-margin-right--1"
    type="button"
  >
    Active
  </button>
  <button
    class="ds-c-button ds-c-button--primary ds-c-button--focus ds-u-margin-right--1"
    type="button"
  >
    Focus
  </button>
  <button class="ds-c-button ds-c-button--primary" disabled="" type="button">
    Disabled
  </button>
</div>

Success Button

Code snippet

<div>
  <button
    class="ds-c-button ds-c-button--success ds-u-margin-right--1"
    type="button"
  >
    Default
  </button>
  <button
    class="ds-c-button ds-c-button--success ds-c-button--hover ds-u-margin-right--1"
    type="button"
  >
    Hover
  </button>
  <button
    class="ds-c-button ds-c-button--success ds-c-button--active ds-u-margin-right--1"
    type="button"
  >
    Active
  </button>
  <button
    class="ds-c-button ds-c-button--success ds-c-button--focus ds-u-margin-right--1"
    type="button"
  >
    Focus
  </button>
  <button class="ds-c-button ds-c-button--success" disabled="" type="button">
    Disabled
  </button>
</div>

Transparent Button

Code snippet

<div>
  <button
    class="ds-c-button ds-c-button--transparent ds-u-margin-right--1"
    type="button"
  >
    Default
  </button>
  <button
    class="ds-c-button ds-c-button--transparent ds-c-button--hover ds-u-margin-right--1"
    type="button"
  >
    Hover
  </button>
  <button
    class="ds-c-button ds-c-button--transparent ds-c-button--active ds-u-margin-right--1"
    type="button"
  >
    Active
  </button>
  <button
    class="ds-c-button ds-c-button--transparent ds-c-button--focus ds-u-margin-right--1"
    type="button"
  >
    Focus
  </button>
  <button
    class="ds-c-button ds-c-button--transparent"
    disabled=""
    type="button"
  >
    Disabled
  </button>
</div>

Button Size Variations

Code snippet

<div>
  <button
    class="ds-c-button ds-c-button--small ds-u-margin-right--1"
    type="button"
  >
    Small
  </button>
  <button class="ds-c-button ds-u-margin-right--1" type="button">
    Default
  </button>
  <button
    class="ds-c-button ds-c-button--big ds-u-margin-right--1"
    type="button"
  >
    Big
  </button>
</div>

Inverse Buttons

Code snippet

<div class="ds-u-fill--background-inverse ds-u-padding--2">
  <div class="ds-u-margin-bottom--2">
    <button
      class="ds-c-button ds-c-button--inverse ds-u-margin-right--1"
      type="button"
    >
      Default
    </button>
    <button
      class="ds-c-button ds-c-button--inverse ds-c-button--hover ds-u-margin-right--1"
      type="button"
    >
      Hover
    </button>
    <button
      class="ds-c-button ds-c-button--inverse ds-c-button--active ds-u-margin-right--1"
      type="button"
    >
      Active
    </button>
    <button
      class="ds-c-button ds-c-button--inverse ds-c-button--focus ds-u-margin-right--1"
      type="button"
    >
      Focus
    </button>
    <button class="ds-c-button ds-c-button--inverse" disabled="" type="button">
      Disabled
    </button>
  </div>
  <div>
    <button
      class="ds-c-button ds-c-button--transparent ds-c-button--inverse ds-u-margin-right--1"
      type="button"
    >
      Default
    </button>
    <button
      class="ds-c-button ds-c-button--transparent ds-c-button--inverse ds-c-button--hover ds-u-margin-right--1"
      type="button"
    >
      Hover
    </button>
    <button
      class="ds-c-button ds-c-button--transparent ds-c-button--inverse ds-c-button--active ds-u-margin-right--1"
      type="button"
    >
      Active
    </button>
    <button
      class="ds-c-button ds-c-button--transparent ds-c-button--inverse ds-c-button--focus ds-u-margin-right--1"
      type="button"
    >
      Focus
    </button>
    <button
      class="ds-c-button ds-c-button--transparent ds-c-button--inverse"
      disabled=""
      type="button"
    >
      Disabled
    </button>
  </div>
</div>

Danger Button

Do not use.

Code snippet

<div>
  <button
    class="ds-c-button ds-c-button--danger ds-u-margin-right--1"
    type="button"
  >
    Default
  </button>
  <button
    class="ds-c-button ds-c-button--danger ds-c-button--hover ds-u-margin-right--1"
    type="button"
  >
    Hover
  </button>
  <button
    class="ds-c-button ds-c-button--danger ds-c-button--active ds-u-margin-right--1"
    type="button"
  >
    Active
  </button>
  <button
    class="ds-c-button ds-c-button--danger ds-c-button--focus ds-u-margin-right--1"
    type="button"
  >
    Focus
  </button>
  <button class="ds-c-button ds-c-button--danger" disabled="" type="button">
    Disabled
  </button>
</div>

Button 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.

Code snippet

<div>
  <button class="ds-c-button ds-u-margin-right--1" type="button">
    <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-1344"
      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 class="ds-c-button ds-u-margin-right--1" type="button">
    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-1345"
      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>
  <button class="ds-c-button" type="button">No Icon</button>
</div>

Button inline with field

The button is the same height as a single-line text field.

Code snippet

<div>
  <input
    type="text"
    class="ds-c-field ds-u-display--inline-block ds-u-margin-right--05"
    aria-invalid="false"
  />
  <button class="ds-c-button" type="button">Submit</button>
</div>

`<Button>`

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.

View Source File

Open in Storybook

Code snippet

Props

React Properties Documentation
Name	Type	Default	Description
`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.
`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.
`children`required	`string \| React.ReactNode`		Label text or HTML
`className`	`string`		Additional classes to be added to the root button element. Useful for adding utility classes.
`disabled`	`boolean`
`href`	`string`		When provided the root component will render as an `<a>` element rather than `button`.
`inputRef`	`MutableRefObject<any> \| ((...args: any[]) => any)`		Access a reference to the `button` or `a` element
`inversed`	`boolean`		Applies the inverse theme styling
`onClick`	`(...args: any[]) => any`		Returns the `SyntheticEvent`. Not called when the button is disabled.
`size`	`'small' \| 'big'`
`type`	`React.ComponentProps<'button'>['type']`	`'button'`	Button `type` attribute
`variation`	`'primary' \| 'danger' \| 'success' \| 'transparent'`		A string corresponding to the button-component variation classes. The `'danger'` variation is deprecated and will be removed in a future release.

Guidance

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

Use the "primary" button variation for the button most users should click. This is your primary call-to-action.
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

Use the "danger" button variation for destructive buttons. For example, buttons that delete or reset a user's information.
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.

Disabled buttons

Don’t disable buttons, unless there’s a good reason to.
If you do disable a button, make sure it receives the disabled styling. A button element will automatically be styled as a disabled button when it has the disabled HTML attribute, but an a element will need to have the .ds-c-button--disabled class applied to it.

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 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.

Customization

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

Variable	Default Core Theme Value
`$button__border-radius`	`3px`
`$button__border-width`	`1px`
`$button__background-color`	`$color-white`
`$button__background-color--active`	`$color-white`
`$button__background-color--disabled`	`$color-white`
`$button__background-color--hover`	`$color-primary-darker`
`$button__border-color`	`$color-primary`
`$button__border-color--active`	`$color-background-inverse`
`$button__border-color--disabled`	`$color-border`
`$button__border-color--hover`	`$color-primary-darker`
`$button__color`	`$color-primary`
`$button__color--active`	`$color-background-inverse`
`$button__color--disabled`	`$color-border`
`$button__color--hover`	`$color-primary-darker`
`$button-icon__fill`	`$color-base`

Learn more

Button alignment

ARIA

Google Analytics

Analytics event tracking is disabled by default.

Enable event tracking

Import and set the setButtonSendsAnalytics feature flag to true in your application's entry file:

import { setButtonSendsAnalytics } from '@cmsgov/<design-system-package>';
setButtonSendsAnalytics(true);

On applications where the page has utag loaded, the data goes to Tealium which allows it to route to Google Analytics or the currently approved data analytics tools.

Disable event tracking

For the analytics prop, pass the value false to the component to disable analytics tracking for a singular component instance

analytics={false}

Override event tracking

A custom heading value can be sent for an analytics event by using the prop analyticsLabelOverride. It is recommended that this value be used to prevent sensitive personal information from being passed to analytics trackers.

Default Button

Primary Button

Success Button

Transparent Button

Button Size Variations

Inverse Buttons

Danger Button

Deprecated

Button icons

Button inline with field

<Button>

Props

Guidance

When to use

When to consider alternatives

Usage

Accessibility

Customization

Learn more

Google Analytics

Enable event tracking

Disable event tracking

Override event tracking

`<Button>`