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

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.
`leftButtonText`	`left-button-text`	`string`		Custom text that will be applied to the left va-button inside the component. If set will override text controlled by the 'update' prop.
`primaryLabel`	`primary-label`	`string`		Applies to the primary button aria-label.
`rightButtonText`	`right-button-text`	`string`		Custom text that will be applied to the right va-button inside the component. If set will override text controlled by the 'update' prop,
`secondaryLabel`	`secondary-label`	`string`		Applies to the secondary button aria-label.
`submit`	`submit`	`string`		Having this attribute present will set the type of this button as 'submit'. The va-button element must be within a `form` element for this functionality to take place A value of: `prevent` will trigger the onsubmit callback on the form, but won't submit the form; `skip` will submit the form but not trigger the onsubmit callback; All other values will trigger the onsubmit and onclick callbacks, then submit the form; in that order.
`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.
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

While this component has been previously tested against older criteria, it has not yet been audited with the updated testing criteria.

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.

90% complete (10 of 11)

Legend:

Complete
Incomplete
Not applicable