Button

Examples

Usage

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 Buttons vs. Links.
• 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. You can use buttons for navigation within a form flow, but otherwise use links. Read the guidance on Buttons vs. Links.
• Call-to-action. For a visually prominent call to action that links to another page, use an Action link.

Behavior

• Avoid using many primary buttons on a single page or section. Using too many primary buttons on a single page or section reduces their impact and makes it harder for users to know what to do next.
• Avoid disabling buttons. Refer to Do not disable buttons for details.
• Use icons only when necessary. Use Icons in buttons only when they add clarity and are highly relevant to the action. Don’t use icons for decoration. Note that va-button doesn’t support iconography but has some variations that include an icon. The team evaluates icon use in buttons on a case-by-case basis. If you need an icon for a button, follow the process for requesting a new icon.
  • Note: Don’t use chevrons in this component. We plan to deprecate chevron usage in the Back and Continue variations.

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. Also, use primary buttons to take the user to the next step in a process.
• Use Secondary for non-primary actions. Use secondary buttons for any actions that you need to downplay against other actions on the page, or in a section. Also, use secondary buttons for actions that happen on the current page.
• Use Big primary buttons for the only action. Use the big variation of the primary button for the only action on the page.
• Use Continue and Back for advancing to the next step and returning to the previous step, respectively. You can use these buttons as a pair from Button group. Don’t use the Back button for navigation only. Reserve it for cases where it also performs an action, similar to how the Continue button submits data.
• Use Loading for actions that should only be triggered once. Use the loading variation when it’s necessary to block the user from additional clicks of a button that might cause transaction issues.
• Use Base, primary and secondary, in dark mode in mobile applications. Use the base variations for dark mode or when primary buttons won’t pass the required color contrast ratio.
• Use destructive for actions that have serious consequences. Use the destructive button for any action that can’t be reversed and may result in data loss. The mobile app currently uses this button when canceling an appointment and when removing contact information.
  • Don’t rely on the red color alone to communicate the destructive nature of the action. Always ensure the button text clearly communicates what will happen.
  • Since destructive buttons have serious consequences, always add friction before completing the action. This can be in the form of a native confirmation message (alert or action sheet) in the mobile app or a modal on web.

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

Primary button with a secondary link

• Links can substitute for secondary buttons. It’s not always necessary to pair a secondary button with a primary button. In the example below, a link also works well for a non-primary action.

Code usage

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 button labels to 35 characters or fewer. The va-button component enforces a 50-character absolute maximum. Labels over 35 characters should only occur in exceptional cases, such as modal actions or form exits, where additional context is needed for clarity. Use “trigger words” that your users will recognize to clearly explain what will happen when the button is clicked (for example, “Back” or “Continue”).
• Don’t truncate button labels. Button labels must always be displayed in full. Teams are responsible for ensuring labels remain clear, meaningful, and complete within the 50-character maximum, regardless of screen size, zoom level, or viewport width.
• Make it an action.

Accessibility considerations

Additional guidance for VA

• Don’t change button labels dynamically or use them to communicate a status.
• Mind target size. We follow the Web Content Accessibility Guidelines (WCAG) 2.2 Target Size (Minimum) - Level AA criteria, which states:

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

• 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. Use it to add a description that is visually hidden but accessible to screen readers.
  • 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. Put crucial information about the button’s purpose in the button label itself. Don’t rely solely on an additional description.

Choose the right element: Buttons vs. links

Many people struggle to select the right element when choosing between a button or link. Making the right choice can help make an interface easier to use, especially for people who use assistive technology. Buttons and links are the primary ways users interact with information on a web page. Links are for navigation; buttons are for action.

Accessibility problem being solved

In general, make links look like links and buttons look like buttons. Designing buttons as buttons and links as links improves usability and accessibility by:

• Setting honest expectations of interaction behavior
• Providing clear signifiers of affordances
• Creating experiences that are consistent with web standards

Assistive technology users rely on proper semantics to access web content. They may choose to navigate by button, or link, depending on what they’re looking for. It’s vital that our content meets users’ expectations - link items, coded as buttons, could make those links hard to find, for example.

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

Ideal state

Buttons are:

• Used for actions, including:
  • Submitting a form
  • Opening a modal
  • Changing the state of something (such as “Back / Continue” buttons on a form)
  • Expanding something (like an accordion)
• Created using the Button component or Button group component, or with standard semantic HTML button
• Styled to look like buttons and shouldn’t include link signifiers, such as underlines

Links are:

• Used for navigation:
  • Navigation bars
  • Skip links / jump links (such as the On this page component)
  • Links to internal web pages
  • Links to external websites (read the Content style guide for additional information)
  • Links to PDFs, whether static or generated on the fly
    • Rationale: The final product is a file, and the Veteran may not know that the PDF is generated on the fly.
    • Exception: If the trigger to generate the PDF is “Generate PDF,” “Create PDF,” or other phrases that explicitly call out the “action” nature of the generation, use a button.
• Created using the Link component, the Action link component if you need extra visual emphasis, or with standard semantic HTML link
  • When a file download is involved, it is best to use the download link component. This is because links are intended for navigation, and downloading a file is a navigational action to a resource.
• Styled to look like links and shouldn’t include button signifiers, such as borders

Implementation notes

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.

Accessibility tests

The Design System team tested this component in isolation across a mix of browsers and assistive technologies using the . Our results may not capture accessibility issues that arise from surrounding context like page structure, content, or how multiple components interact.

To ensure accessibility, you must also test the Button component within your own product. See the for what we tested and what you need to test.

Privacy guidance

Buttons shouldn’t include Personally Identifiable Information (PII) or Protected Health Information (PHI).

• This includes the button text as well as the URL referenced in the link, when applicable
  Learn more on the URLs component page
• If the button text must include PII/PHI, click events for that button can’t be tracked in analytics or other logs
  Learn more on the Button labels page in the content style guide

Learn more about PII/PHI on the VA Platform website

Component checklist

Provide feedback

Share your feedback, report issues, or suggest improvements for the Button component. Your input helps us make the design system better for everyone.

• Get immediate support in #platform-design-system for technical or urgent issues.
• Explore all feedback channels for additional ways to share your input.