Skip to main content
U.S. Flag

An official website of the United States government

Button

Buttons allow users to take actions from a current state to a future state.

Notice:

Are 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:

  1. Variation: which affects the border and background styles
  2. Color: defined as either main or alternate
  3. 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
VariationMain (Default)Alternate
Outline (Default)
Solid
Ghost
Button variations on dark background
VariationMain (Default)Alternate
Outline (Default)
Solid
Ghost

Main buttons

Solid button

Loading

Outline button

Loading

Ghost button

Loading

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

Loading

Alternate outline button

Loading

Alternate ghost button

Loading

On dark background

Loading

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.

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
NameTypeDefaultDescription
analyticsboolean

Analytics events tracking is enabled by default. Set this value to false to disable tracking for this component instance.

analyticsLabelOverridestring

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.

analyticsParentHeadingstring

If needed for analytics, pass heading text of parent component of button.

analyticsParentTypestring

If needed for analytics, pass type of parent component of button.

childrenrequiredstring | React.ReactNode

Label text or HTML

classNamestring

Additional classes to be added to the root button element.

disabledboolean
hrefstring

When provided, the root component will render as an <a> element rather than button.

inputRefMutableRefObject<any> | ((...args: any[]) => any)

Access a reference to the button or a element

isAlternatebooleanfalse

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.

onDarkbooleanfalse

Defines a color palette best used when Button is placed on a dark background-color. By default, Button uses a light color palette.

size'small' | 'big'
typeReact.ComponentProps<'button'>['type']'button'

Button type attribute

variation'solid' | 'ghost'

A string corresponding to Button variation classes.

Styles

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

Sass variables for button
VariableDefault Core Theme Value
$button__background-color--active$color-border
$button__background-color--disabledtransparent
$button__background-color--hover$color-gray-lightest
$button__background-colortransparent
$button__border-color--activecurrentColor
$button__border-color--disabledcurrentColor
$button__border-color--hovercurrentColor
$button__border-colorcurrentColor
$button__border-radius3px
$button__border-width1px
$button__color--active$color-background-inverse
$button__color--disabled$color-border
$button__color--hover$color-primary-darker
$button__color$color-primary
$button__font-weight700
$button-icon__fillcurrentColor

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.

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.

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.

Learn more

Button alignment

ARIA