Components

Button groups

Use button groups to collect similar or related actions

General accessibility guidance for button groups

  • Convey relationship. If not using a list element, give the parent element role="group" in order to convey to screen readers that actions are part of a group. If using as part of a toolbar, use role="toolbar".

General implementation guidance for button groups

  • Buttons inside of a button group follow the same guidelines as the button component.
  • Button groups support any style and size.

Default

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

Default
1
2
3
4
5
6
7
8
9
<h6>Default</h6>
<ul class="usa-button-group">
  <li class="usa-button-group__item">
    <a href="#" class="usa-button usa-button--outline">Back</a>
  </li>
  <li class="usa-button-group__item">
    <button class="usa-button">Continue</button>
  </li>
</ul>

When to use the default button groups

  • Actions have a contextual relationship. For example, the default button group can be used when a form has both a primary and alternative action.
  • Stepping through linear content. Buttons in a button group can be used for directional navigation and actions (e.g., "Back," "Next," "Continue," "Skip," "Cancel.").

When to consider something else

  • If actions are not related. Consider how placement and alternative structure of unrelated actions can improve usability over placing all actions in a group.
  • When mixing destructive and non-destructive actions. This can lead to input mistakes.
  • Linking to content. Buttons in button groups should not be used when text links would be simpler and more contextually appropriate. Grouped buttons such as "Next" and "Previous" are acceptable when content is organized sequentially.

Usability guidance

  • Avoid burden of choice. Try not to present the user with too many options.

Implementation

  • Because the button group uses flexbox, there are several ways modify how the default button group is displayed.
    • The default button group will display as a column on smaller screen sizes. To override this behavior and display buttons in a row for all screen sizes, use the flex-row utility.
    • On smaller screens, the first button in the source order will appear at the top of column. You can change this behavior using the order utility. The order utility includes responsive advanced settings that allow it to target specific screen sizes.
    • Instead of each button appearing on the left-hand side on larger screens (or if you used flex-row), you can use flex-justify to justify the buttons
Button group settings

This component has no settings.

Button group variants
Variant Description
usa-button-group--segmented Display a group of buttons in a row as a single element.

Package information

  • Package usage: @import usa-button-group
  • Requires: required, global

Segmented

Segmented button groups display a set of discrete buttons in a row as a single element.

Segmented
1
2
3
4
5
6
7
8
9
10
11
12
<h6>Segmented</h6>
<ul class="usa-button-group usa-button-group--segmented">
  <li class="usa-button-group__item">
    <button class="usa-button">Map</button>
  </li>
  <li class="usa-button-group__item">
    <button class="usa-button usa-button--outline">Satellite</button>
  </li>
  <li class="usa-button-group__item">
    <button class="usa-button usa-button--outline">Hybrid</button>
  </li>
</ul>

When to use the segmented button groups

  • Categorically related controls. For example, segmented buttons can be used as a switch between different views.

When to consider something else

  • No clear relationship. Consider how placement and alternative structure of unrelated controls can improve usability over placing all actions in a group.
  • If there are more than three buttons. Be mindful of how a long list of buttons might appear on small screens. An alternative type of control might be more suitable.

Usability guidance

  • Avoid ambiguity of current state. Make sure current states are clearly communicated and understood.

Accessibility

  • Use aria-label to give the buttons a useful name. Some contexts may require additional context provided to screen readers.
  • Use the <button> element. Don't use <a> because it's a link. Don't use <span> because screen readers won't know it's a usable button.

Implementation

  • Don't mix differently-sized buttons (like a default button and a big button) in the same group.
  • Use short, descriptive button labels to describe controls.
  • Use default buttons as a current state and outline buttons as a non-current state. The segmented button group works with all button variants. However, you may need to create custom styles to distinguish state for some button variants.

Package information

  • Package usage: @import usa-button-group
  • Requires: required, global