An official website of the United States government
Here’s how you know
Official websites use .gov A
.gov website belongs to an official government
organization in the United States.
Secure .gov websites use HTTPS A
lock (
) or https:// means you’ve safely connected to
the .gov website. Share sensitive information only on official,
secure websites.
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 component in your own project.
USWDS tested the button component for accessibility. You should test your implementation, too.
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.
Breaking
Updated the width of unstyled buttons at narrow screen widths.
Now, unstyled buttons receive a width of auto to better match USWDS link styles.
Users should confirm that the variant visually displays as expected in their projects.
More information:
uswds#5631
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
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
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
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
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
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
