Components

Button pair

Use with caution: Candidate

USWDS v3

The default button group arranges each button as a separate element with a gap between them. On mobile devices, the buttons are arranged vertically.

Examples - v1

Examples - v3

Default

View Default v3 button pair along with additional variations in Storybook

Usage

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

Additional guidance for VA

NOTE: We will be changing the name of this component from button-pair to button-group to align with the USWDS.
NOTE: We do not yet offer the Segmented button group option.

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 primary button being on top of the secondary 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 primary button continuing to appear before the secondary button.

Choosing between variations

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.

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 aria-label.
`secondaryLabel`	`secondary-label`	`string`		Applies to the secondary button aria-label.
`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.
`uswds`	`uswds`	`boolean`	`false`	Whether or not the component will use USWDS v3 styling.

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.
Refer to our guidance for the Button component

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