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 pair

Use with caution: Candidate
Use button pairs to provide navigation through a form flow or a primary and secondary action.

Examples

Default (Yes/No)

View Default button pair in Storybook

Update/Cancel

View Update/Cancel button pair in Storybook

Back/Continue

View Back/Continue button pair in Storybook

Usage

When to use a button pair

  • Use the default button pair variation to provide primary and secondary response options to a question.
  • Use the Update/Cancel button pair variation for saving form input on a form.
  • Use the Back/Continue button pair variation for providing navigation options through a step by step flow of form pages.

When to consider something else

  • Navigation outside of the flow. For navigation to pages outside of the form flow, use a link.
  • Call-To-Action. For a visually prominent call to action (CTA) 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.
  • Arrows are reserved. Arrow icons should only appear for the Back/Continue button pair.

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) with the secondary button continuing to appear before the primary button.
  • It is also acceptable for the buttons to be half-width and centered at smaller viewport sizes, as they are in the Back/Continue button pair variation.

Placement

  • A button pair appears at the bottom of a form.

Design principles

  • Fitts’s Law is important to keep in mind when determining button sizing and placement. Touch targets should be placed where they can be easily and quickly acquired. For example, this is why we do not split the buttons far apart, aligning them to different sides of the viewport. Fitts’s Law states:

The time to acquire a target is a function of the distance to and size of the target

Code usage

Attributes and Properties

Property Attribute Type Default Description
continue continue boolean false If `true`, button pair will use Continue and Back for button text.
disableAnalytics disable-analytics boolean false If `true`, the component-library-analytics event is disabled.
primaryLabel primary-label string Applies to the primary button.
secondaryLabel secondary-label string Applies to the secondary button.
submit submit boolean false If `true`, the primary button will submit form data when clicked.
update update boolean false If `true`, button pair will use Update and Cancel for button text.

Events

Name Description
component-library-analytics The event used to track usage of the component.
primaryClick Fires when the primary button is clicked.
secondaryClick Fires when the secondary button is clicked.

Accessibility considerations

  • Include more contextual information in the button label for screen readers. You can use an aria label, using the ariaLabel or ariaDescribedby properties, to specify form numbers or program names in the buttons for greater context.
  • 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.
Edit this page in GitHub (Permissions required)
Last updated: Aug 02, 2022