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 group

Also known as: Button pair

Use: Deployed 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 - v3

Default (Yes/No)

View Default v3 button pair along with additional variations in Storybook

Update

View Update/Cancel button pair in Storybook

Continue

View Back/Continue button pair in Storybook

Examples - v1

Default (Yes/No)

View Default button pair 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 group.

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 group variation to provide primary and secondary response options to a question.
  • Use the Update/Cancel button group variation for saving form input on a form.
  • Use the Back/Continue button group variation for providing navigation options through a step by step flow of form pages.

Placement

  • A button group 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 true 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.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

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.
93% complete (15 of 16)

Legend:

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