Components

Button

A button draws attention to important actions with a large selectable surface.

Passed WCAG 2.1 AA

Default

Secondary color

Accent cool color

Accent warm color

Base color

Outline

Outline inverse

Big button

<h3 class="site-preview-heading">Default</h3>
<button class="usa-button" type="button">Default</button>
<button class="usa-button usa-button--hover" type="button">Hover</button>
<button class="usa-button usa-button--active" type="button">Active</button>
<button class="usa-button usa-focus" type="button">Focus</button>
<button class="usa-button" type="button" disabled="disabled">Disabled</button>
<button class="usa-button" type="button" aria-disabled="true">
  aria-disabled
</button>
<button class="usa-button usa-button--unstyled" type="button">
  Unstyled button
</button>

<h3 class="site-preview-heading">Secondary color</h3>
<button class="usa-button usa-button--secondary" type="button">Default</button>
<button
  class="usa-button usa-button--secondary usa-button--hover"
  type="button"
>
  Hover
</button>
<button
  class="usa-button usa-button--secondary usa-button--active"
  type="button"
>
  Active
</button>
<button class="usa-button usa-button--secondary usa-focus" type="button">
  Focus
</button>
<button
  class="usa-button usa-button--secondary"
  type="button"
  disabled="disabled"
>
  Disabled
</button>
<button
  class="usa-button usa-button--secondary"
  type="button"
  aria-disabled="true"
>
  aria-disabled
</button>
<button
  class="usa-button usa-button--secondary usa-button--unstyled"
  type="button"
>
  Unstyled button
</button>

<h3 class="site-preview-heading">Accent cool color</h3>
<button class="usa-button usa-button--accent-cool" type="button">
  Default
</button>
<button
  class="usa-button usa-button--accent-cool usa-button--hover"
  type="button"
>
  Hover
</button>
<button
  class="usa-button usa-button--accent-cool usa-button--active"
  type="button"
>
  Active
</button>
<button class="usa-button usa-button--accent-cool usa-focus" type="button">
  Focus
</button>
<button
  class="usa-button usa-button--accent-cool"
  type="button"
  disabled="disabled"
>
  Disabled
</button>
<button
  class="usa-button usa-button--accent-cool"
  type="button"
  aria-disabled="true"
>
  aria-disabled
</button>
<button
  class="usa-button usa-button--accent-cool usa-button--unstyled"
  type="button"
>
  Unstyled button
</button>

<h3 class="site-preview-heading">Accent warm color</h3>
<button class="usa-button usa-button--accent-warm" type="button">
  Default
</button>
<button
  class="usa-button usa-button--accent-warm usa-button--hover"
  type="button"
>
  Hover
</button>
<button
  class="usa-button usa-button--accent-warm usa-button--active"
  type="button"
>
  Active
</button>
<button class="usa-button usa-button--accent-warm usa-focus" type="button">
  Focus
</button>
<button
  class="usa-button usa-button--accent-warm"
  type="button"
  disabled="disabled"
>
  Disabled
</button>
<button
  class="usa-button usa-button--accent-warm"
  type="button"
  aria-disabled="true"
>
  aria-disabled
</button>
<button
  class="usa-button usa-button--accent-warm usa-button--unstyled"
  type="button"
>
  Unstyled button
</button>

<h3 class="site-preview-heading">Base color</h3>
<button class="usa-button usa-button--base" type="button">Default</button>
<button class="usa-button usa-button--base usa-button--hover" type="button">
  Hover
</button>
<button class="usa-button usa-button--base usa-button--active" type="button">
  Active
</button>
<button class="usa-button usa-button--base usa-focus" type="button">
  Focus
</button>
<button class="usa-button usa-button--base" type="button" disabled="disabled">
  Disabled
</button>
<button class="usa-button usa-button--base" type="button" aria-disabled="true">
  aria-disabled
</button>
<button class="usa-button usa-button--base usa-button--unstyled" type="button">
  Unstyled button
</button>

<h3 class="site-preview-heading">Outline</h3>
<button class="usa-button usa-button--outline" type="button">Default</button>
<button class="usa-button usa-button--outline usa-button--hover" type="button">
  Hover
</button>
<button class="usa-button usa-button--outline usa-button--active" type="button">
  Active
</button>
<button class="usa-button usa-button--outline usa-focus" type="button">
  Focus
</button>
<button
  class="usa-button usa-button--outline"
  type="button"
  disabled="disabled"
>
  Disabled
</button>
<button
  class="usa-button usa-button--outline"
  type="button"
  aria-disabled="true"
>
  aria-disabled
</button>
<button
  class="usa-button usa-button--outline usa-button--unstyled"
  type="button"
>
  Unstyled button
</button>

<h3 class="site-preview-heading">Outline inverse</h3>
<div class="bg-base-darkest padding-1" style="max-width: fit-content">
  <button
    class="usa-button usa-button--outline usa-button--inverse"
    type="button"
  >
    Default
  </button>
  <button
    class="usa-button usa-button--outline usa-button--inverse usa-button--hover"
    type="button"
  >
    Hover
  </button>
  <button
    class="usa-button usa-button--outline usa-button--inverse usa-button--active"
    type="button"
  >
    Active
  </button>
  <button
    class="usa-button usa-button--outline usa-button--inverse usa-focus"
    type="button"
  >
    Focus
  </button>
  <button
    class="usa-button usa-button--outline usa-button--inverse"
    type="button"
    disabled="disabled"
  >
    Disabled
  </button>
  <button
    class="usa-button usa-button--outline usa-button--inverse"
    type="button"
    aria-disabled="true"
  >
    aria-disabled
  </button>
  <button
    class="usa-button usa-button--outline usa-button--inverse usa-button--unstyled"
    type="button"
  >
    Unstyled button
  </button>
</div>

<h3 class="site-preview-heading">Big button</h3>
<button class="usa-button usa-button--big" type="button">Default</button>
<button class="usa-button usa-button--big" type="button" disabled="disabled">
  Disabled
</button>
<button class="usa-button usa-button--big" type="button" aria-disabled="true">
  aria-disabled
</button>
<button class="usa-button usa-button--big usa-button--unstyled" type="button">
  Unstyled button
</button>

Guidance

When to use the button component

  • Important actions. Use buttons for the most important actions you want users to take on your site, such as Download, Sign up or Log out.

When to consider something else

  • Linking between a site’s pages. Use regular links instead.
  • If the action is less popular or less important. Less popular or less important actions may be visually styled as links.

Usability guidance

  • Use standard buttons for actions that go a next step.
  • Use outline buttons for actions that happen on the current page.
  • Give an important action a distinctive style. Style the button most users should select in a way that distinguishes it from other buttons on the page. Try using the usa-button--big variant or the most visually distinct color variant.
  • Make sure buttons look selectable. Use color variations to distinguish static, hover, and active states.
  • Avoid using too many buttons on a page.
  • Use sentence-case capitalization for button labels.
  • Keep button text short. Button text should be as short as possible with action words that clearly explain what will happen when the button is selected (for example, Download, View, or Sign up).
  • Lead with a verb. Make the first word of the button’s text a verb. For example, instead of Complaint filing, label the button File a complaint.
  • Icons can be helpful. Consider adding an icon to signal specific actions (Download, Open in a new window, etc).

Accessibility guidance

Test the button in your own project.

USWDS tested the button component for accessibility. You should test your implementation, too.

Use button accessibility tests
  • Buttons should display a visible focus state when users tab to them.
  • Use standard markup. Avoid using <div> or <img> tags to create buttons. Screen readers don’t automatically know either is a usable button.
  • Screen readers handle buttons and links differently. 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.

Using the button component

  • Always set the type attribute. Define the purpose and behavior of a button with the type attribute. The type attribute can accept three values: submit, button, and reset. If no type attribute is defined, the button will behave as a submit button.
  • Use the disabled or aria-disabled attributes to turn on disabled button styles.
  • Add button styles to links. To use a button style on a link, add the usa-button class to your link. Add an additional button variant class to access variant styles.

Button settings

Variable Description
$theme-button-border-radius

Button border radius for rounded corners.

$theme-button-font-family

Font family of the button.

$theme-button-icon-gap

Size of the gap between the button’s text and icon.

$theme-button-small-width

Width of small buttons. Used to define the size of the header search button and small language selector button.

$theme-button-stroke-width

Stroke width of outline button variants.

Button variants

Variant Description

.usa-button--secondary

Button uses secondary color.

.usa-button--accent-cool

Button uses accent-cool color.

.usa-button--accent-warm

Button uses accent-warm color.

.usa-button--base

Button uses base color.

.usa-button--outline

Transparent button with a color stroke.

.usa-button--inverse

Light color button for dark backgrounds.

.usa-button--big

A bigger button.

.usa-button--unstyled

A button that looks like a link.

Accessibility test status

The USWDS team did 9 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
9 6 1 2 0

Overview of recent accessibility test results:

  • Passed: 6
  • Passed with exceptions: 1
  • Conditional: 2
  • Failed: 0

Learn more on the button accessibility tests page.

Package

  • Package usage: @forward "usa-button";
  • Dependencies: uswds-fonts

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-03-11 3.8.0
  • Styles
  • Settings
No

Added a new setting to adjust the gap between the button’s text and icon. Gap between elements can be adjusted using the $theme-button-icon-gap setting. More information: uswds#5398

2024-03-11 3.8.0
  • Styles
  • Settings
No

Improved the vertical alignment of usa-icon when placed inside of usa-button. More information: uswds#5398

2024-01-17 N/A
  • Guidance
No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2138

2023-11-20 N/A
  • Guidance
No

Updated summaries in the “Using the button component” section. More information: uswds-site#2149

2023-06-09 3.5.0
  • Accessibility
  • Markup
No

Fixed a bug that caused the button type attribute to render empty. More information: uswds#5247

2023-06-09 3.5.0
  • Accessibility
  • Styles
No

Improved consistency and visibility of disabled styles. Form elements with the disabled or aria-disabled attribute now get consistent styling and have proper color contrast. More information: uswds#5063

2023-06-09 3.5.0
  • Accessibility
  • Styles
No

Improved consistency of disabled styles in forced colors mode. More information: uswds#5295

2023-06-09 3.5.0
  • Accessibility
  • Styles
No

Improved legibility in forced colors mode. Adds a consistent border in forced colors mode. More information: uswds#5147

2023-06-09 3.5.0
  • Accessibility
  • JavaScript
No

Added spacebar trigger to links styled as buttons. More information: uswds#4385

2022-08-05 3.1.0
  • Accessibility
  • Styles
No

Styled aria-disabled to match disabled. Now disabled styling is applied whether you use disabled (disabled and hidden from screen readers) or aria-disabled (disabled and visible to screen readers). More information: uswds#4783

2022-08-05 3.1.0
  • JavaScript
  • Markup
Breaking

Breaking Added type="button" to all non-form buttons to prevent default submit behaviors. This allowed us to remove preventDefault() from the relevant component JavaScript. More information: uswds#4695

2022-06-03 N/A
  • Guidance
No

Added guidance for using the button type attribute. More information: uswds-site#1608

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2021-06-08 N/A
  • Guidance
No

Added guidance to use the disabled attribute instead of .usa-button--disabled. More information: uswds-site#1232

2021-04-28 2.11.2
  • Styles
No

Fixed unstyled button styling. We updated and strengthened the styling of unstyled buttons to prevent any unwanted style leakage from conventional buttons, especially is used in conjunction with usa-button--hover and usa-button--active classes. More information: uswds#4077

2020-12-17 2.10.0
  • Styles
No

Improved support for buttons with multiple variants. We fixed a display bug with visited inverse unstyled buttons. Button styling is more reliable with different combinations of variants. More information: uswds#3846