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.


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.



Use: Deployed USWDS v3
A button draws attention to important actions with a large selectable surface.


Default - Primary

View va-button–primary in Storybook

Default - Secondary

View va-button–secondary in Storybook

Default - Big

View va-button–big in Storybook


View va-button–continue in Storybook


View va-button–back in Storybook


Refer to the U.S. Web Design System for usage guidance

Additional guidance for VA

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


  • 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.
  • Use icons only when necessary. Icons can be used in buttons when additional clarity is required and the icon is highly relevant to the action. Icons should not be used for decoration. Note that va-button does not support iconography, but has some variations that use an icon. Use of icons in buttons will be made on a case-by-case basis. If you feel you need an icon for a button, follow the process for requesting a new icon .
  • Avoid disabling buttons. Disabling buttons is strongly discouraged.

Choosing between variations

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


  • 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-dark 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.
messageAriaDescribedby message-aria-describedby string An optional message that will be read by screen readers when the input is focused.
primaryAlternate primary-alternate boolean false If `true`, the button will use the primary alternate variant.
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.
uswds uswds boolean true Whether or not the component will use USWDS v3 styling.


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

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.

For simple navigation to lead people between pages, use links instead of buttons.

  • Use sentence case for button labels (except for Button - Icon).
  • Make button labels as short as possible.
  • Use “action 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 health care.
    • Like this: “Apply for VA health care” button should take you to an application page like Apply for VA healthcare.
    • Like this: “Compare GI Bill benefits” button should take you right to the GI Bill® Comparison Tool.

Accessibility considerations

Refer to the U.S. Web Design System for accessibility guidance

Additional guidance for VA

  • Button labels should never change dynamically or be used to communicate a status.
  • Mind target size. We follow the WCAG 2.2 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.”

  • Use at least 1 spacing unit separating tappable elements.

  • Prioritize a clear and concise button label and only use message-aria-describedby when it enhances understanding and accessibility. The message-aria-describedby property emulates HTML’s aria-describedby due to web component limitations. It allows adding an additional description that is visually hidden, but screen reader accessible.

    • When to use:
      • Providing additional context or instructions. If the button label is concise but requires further explanation.
    • When not to use:
      • Duplicating information. If the button’s label is clear and concise, adding additional information may be redundant and cumbersome for users of assistive technology.
      • Providing essential information. Crucial information for the button’s purpose should be the button label itself, not solely relying on an additional description.
  • 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 form elements

Disabling form elements is discouraged as a design crutch. Thus most of our form components do not support a disabled property. If you feel that you have a unique design problem that requires a disabled field you may lobby the accessibility Community of Practice and the Design System Council but know that, thus far, exceptions to this rule are rarely granted.

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.

Component checklist


Examples, usage, code usage, content considerations, and accessibility considerations are all complete.
VFS team conducted research on this component which is linked from this page.
Component has been in production for more than 3 months with no significant issues found.
Multiple teams have adopted this component.


Accessible use of color
Color is not used as the only visual means of conveying information (WCAG 2.2 1.4.1).
Accessible contrast
Text has a contrast ratio of at least 4.5:1 for small text and at least 3:1 for large text (WCAG 2.2 1.4.3). Visual information required to identify components and states (except inactive components) has a contrast ratio of at least 3:1 (WCAG 2.2 1.4.11).
Keyboard interactions
Follows WCAG 2.2 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions. All interactive elements can be selected and activated using the keyboard.
Content zoom tested
Component has been tested with the display set to 400% at 1280px viewport width to ensure that the component does not have overlapping text or elements and all interactive elements still operate.
Tested in screen readers
Tested with screen readers to ensure there are no issues with reading order, spelling, dynamic content, and interactive elements.

Code assets

Storybook includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Component depicted in all responsive breakpoints.
Interactive states
Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
All design attributes (color, typography, layout, etc.) are available as tokens.
Describes i18n attributes.

Visual assets

Sketch library includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Component designed to work in all responsive breakpoints.
Interactive states
Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
All design attributes (color, typography, layout, etc.) are available as tokens.
93% complete (14 of 15)


  • Complete
  • Incomplete
  • Not applicable
Edit this page in GitHub (Permissions required)
Last updated: May 17, 2024