Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Components

Button

Use with caution: Candidate
Use buttons to signal actions.

Examples

Primary button

View va-button–primary in Storybook

Secondary button

View va-button–secondary in Storybook

Big button

Any button can be made bigger by adding a class name of usa-button-big to the button.

View va-button–big in Storybook

Disabled button

View va-button–disabled in Storybook

Usage

When to use a button

  • Actions. Use buttons for clickable actions you want users to take on a page, such as “Add”, “Close”, “Cancel”, or “Save.” Buttons do things, links go places. Refer to guidance on Links vs. buttons.
  • Triggers. Buttons can also trigger functionality via Javascript. For example, closing a modal window.

When to use a primary button

  • Use primary for the most important action. Use the primary button for the most important action that you want the user to take on the page, or in a section.

When to use a secondary button

  • Use secondary for non-primary actions. Use secondary buttons for any actions that need to be downplayed against other actions on the page, or in a section.

When to consider something else

  • Non-actions. For navigation between pages of a website, default to using links. Buttons can be used for navigation between pages within a form flow but otherwise use links. Read the guidance on links vs. buttons.
  • Call-to-action. For a visually prominent call to action that links to another page, use an Action link.

Behavior

  • Avoid using too many buttons on a page. Pages with many buttons may signal that the page content needs to be split up.
  • Avoid using many primary buttons on a single page or section. Pages with many primary buttons reduces their impact and make it harder for users to know what to do next.
  • Arrows are reserved. Arrow icons should only appear for “Back” and “Continue” buttons that appear in forms.
  • Avoid disabling buttons. Disabling buttons is strongly discouraged.

Mobile behavior

  • Primary and secondary buttons should appear full-width up until the small-screen breakpoint with the secondary button being on top of the primary button with 2 spacing unit of separation between them.
  • At and after the small-screen breakpoint the buttons left align and revert to a natural width (i.e. as wide as they need to be to accommodate their label).

Choosing between variations

  • Use the primary button for the primary action and the secondary button for actions that need to be downplayed against the primary action.

Placement

  • Buttons generally appear on their own line at the bottom of a form or section.
  • Primary buttons usually appear first, or to the left, of a secondary button.

Instances of this component in production

  • Links can substitute for secondary buttons. It is not always necessary to pair a secondary button with a primary button. In the example below a link can also suffice for a non-primary action.
Example of a primary button with a secondary link.
An example of a primary button used with a secondary link.

Secondary button as radio button

This variation substitutes the large tap target of a button where a radio button would traditionally be used. This serves a similar purpose to the USWDS Tile variation of a Radio button.

  • Limit to Yes/No. This variation should be limited to Yes/No questions rather than used as a substitute for radio buttons which can more readily handle 3 or more responses.
  • Reflect selections. The response of the user must change the button from a secondary button to a $color-primary-darker background in order to reflect the state of the user’s response.
Example of the secondary button as radio button substitution.
The COVID-19 Screener uses secondary buttons instead of radio buttons for Yes/No questions.

Code usage

Attributes and Properties

Property Attribute Type Default Description
back back boolean false If `true`, the button will use `Back` as its text and an icon to represent going back in form flows.
big big boolean false If `true`, the button will use the big variant.
continue continue boolean false If `true`, the button will use `Continue` as its text and an icon to represent proceeding forward in form flows.
disableAnalytics disable-analytics boolean false If `true`, the component-library-analytics event is disabled.
disabled disabled boolean false If `true`, the click event will not fire.
label label string The aria-label of the component.
secondary secondary boolean false If `true`, the button will use the secondary variant.
submit submit boolean false If `true`, the button will submit form data when clicked.
text text string The text displayed on the button. If `continue` or `back` is true, the value of text is ignored.

Events

Name Description
component-library-analytics The event used to track usage of the component.
click

Content considerations

Button labels

Buttons signal important calls to action (CTA) and help people quickly see what’s the most important action they need to take on a page. Treat buttons like important or primary content, and prioritize their placement on pages as you would essential information.

Use links for secondary or less important actions on a page. Likewise, for simple navigation to lead people between pages, use links instead of buttons.

  • Use sentence case for button labels.
  • Make button labels as short as possible.
  • Use “trigger words” that people recognize and clearly signal what will happen when they click the button.
  • Keep the character limit for button labels to 35 characters. 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, “Back” or “Continue”).

Like this

Create an account

Not this

Get started

  • Make it an action.

Like this

File a complaint

Not this

Complaint filing

  • Always take users to the right level of access for the CTA.

    Like this: “Explore VA health care” button should take you to a general health care benefits landing page like va.gov/health-care.

    Like this: “Apply for VA health care” button should take you to an application page like va.gov/health-care/apply.

    Like this: “Compare GI Bill benefits” button should take you right to the comparison tool, va.gov/gi-bill-comparison-tool.

Accessibility considerations

  • When using the <button> element, always specify a type.
  • Buttons should display a visible focus state when users tab to them.
  • Avoid using <div> or <img> tags to create buttons. Screen readers don’t automatically know either is a usable button.
  • Include more contextual information in the button label for screen readers. You can use an aria label to specify form numbers or program names in the buttons for greater context.
  • Button labels should never change dynamically or be used to communicate a status.
  • We follow the WCAG 2.1 Target Size - Level AAA criteria which states:

    “The size of the target for pointer inputs is at least 44 by 44 CSS pixels…”

That guidance agrees with Apple’s Human Interface Guidelines which recommend that:

“On a touchscreen, buttons need a hit target of at least 44x44 points to accommodate a fingertip. On all screens, it’s essential to include enough space around a button so that people can visually distinguish it from surrounding components and content, whether people use touch, a pointer, or a system that expands a button when it’s in focus.”

  • Using links and buttons intentionally results in a more inclusive experience for assistive technology users. Make sure to read both buttons and Action Link guidance to determine when you should use each component.
  • It is important to use Action Links for calls to actions that link to another page rather than buttons, because screen readers always say “link” before links, and “button” before buttons.
  • A good rule is if the action changes the URL, it should not be a button.
  • Button and link confusion can be very frustrating for assistive technology users. A user with a screen reader may pull up a list of links and may not find a specific link because it turns out that it’s been designated as a button in the markup.

Do not disable buttons

Normally, with regular form controls, it is best to fully remove anything the user can’t interact with or which serves no purpose. However, disabling a “button” to act as a guide to the level of form completion (i.e. you are not able to proceed to the next step until the form contains enough data) is a common anti-pattern.

Disabled buttons don’t explain what’s wrong

When buttons are inactive, some users– particularly those with cognitive disabilities- may not know how to activate them. Disabled buttons don’t explain what’s wrong. 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. For example, if someone were to type in a short acronym like “VA” to search and the button doesn’t become accessible, they may think the search field is broken.

In addition, disabled buttons can be unintentionally read out and accessed by mobile screen readers using touch controls.

What to do instead

While it is technically possible, we strongly discourage disabling buttons. Here are recommendations on how to handle specific interactions:

  • Lack of required fields. When a user attempts to submit a form without entering all required form fields:
    • Announce the error and shift focus to the first unfilled required form field.
    • Properly indicate required form elements (the right thing will happen for you when you use the required property on form fields in the Design System).
  • No longer valid options. If certain options in a form are no longer valid then there are two options:
    1. Replace the form elements that can no longer be changed with text representing the current value instead of the current value within a disabled input.
    2. Hide the form elements that are no longer valid.

Is it ever valid to disable a button?

Post-form submission or post-action it can be appropriate to disable the submit or action button as the system is in-between states and loading or taking action. This behavior is often seen on buttons that make a purchase or reservation to prevent the user from accidentally triggering the action multiple times.

Edit this page in GitHub (Permissions required)
Last updated: Aug 16, 2022