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.
component-library-analytics

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.

Component checklist

Maturity

Guidance
Examples, usage, code usage, content considerations, and accessibility considerations are all complete.
Research
VFS team conducted research on this component which is linked from this page.
Stability
Component has been in production for more than 3 months with no significant issues found.
Adoption
Multiple teams have adopted this component.
Note: This component was introduced in July 2022.

Accessibility

Accessible use of color
Color is not used as the only visual means of conveying information (WCAG 2.0 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.0 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.1 1.4.11).
Keyboard interactions
Follows WCAG 2.0 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

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

Visual assets

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

Legend:

  • Complete
  • Incomplete
  • Not applicable
Edit this page in GitHub (Permissions required)
Last updated: Sep 30, 2022