Components

Button group

A button group collects similar or related actions.

Default button group

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

<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 type="button" class="usa-button">Continue</button>
  </li>
</ul>

Guidance

When to use the default button group

  • 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.

Accessibility guidance

  • 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".

Using the default button group

  • Buttons inside of a button group follow the same guidelines as the button component.
  • Button groups support any style and size.
  • Because the button group uses flexbox, there are several ways to 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

Package

  • Package usage: @forward "usa-button-group";
  • Dependencies: usa-button

Segmented button group

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

<ul class="usa-button-group usa-button-group--segmented">
  <li class="usa-button-group__item">
    <button type="button" class="usa-button">Map</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--outline">Hybrid</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--outline">
      Satellite
    </button>
  </li>
</ul>
<ul class="usa-button-group usa-button-group--segmented">
  <li class="usa-button-group__item">
    <button type="button" class="usa-button">Map</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button">Hybrid</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button">Satellite</button>
  </li>
</ul>
<ul class="usa-button-group usa-button-group--segmented">
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--accent-cool">
      Map
    </button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--accent-cool">
      Hybrid
    </button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--accent-cool">
      Satellite
    </button>
  </li>
</ul>
<ul class="usa-button-group usa-button-group--segmented">
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--accent-warm">
      Map
    </button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--accent-warm">
      Hybrid
    </button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--accent-warm">
      Satellite
    </button>
  </li>
</ul>
<ul class="usa-button-group usa-button-group--segmented">
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--base">Map</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--base">Hybrid</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--base">Satellite</button>
  </li>
</ul>
<ul class="usa-button-group usa-button-group--segmented">
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--big">Map</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--big">Hybrid</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--big">Satellite</button>
  </li>
</ul>
<ul class="usa-button-group usa-button-group--segmented">
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--outline">Map</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--outline">Hybrid</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--outline">
      Satellite
    </button>
  </li>
</ul>
<div class="bg-base-darkest padding-1" style="max-width: fit-content">
  <ul class="usa-button-group usa-button-group--segmented">
    <li class="usa-button-group__item">
      <button
        type="button"
        class="usa-button usa-button--outline usa-button--inverse"
      >
        Map
      </button>
    </li>
    <li class="usa-button-group__item">
      <button
        type="button"
        class="usa-button usa-button--outline usa-button--inverse"
      >
        Hybrid
      </button>
    </li>
    <li class="usa-button-group__item">
      <button
        type="button"
        class="usa-button usa-button--outline usa-button--inverse"
      >
        Satellite
      </button>
    </li>
  </ul>
</div>
<ul class="usa-button-group usa-button-group--segmented">
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--secondary">Map</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--secondary">
      Hybrid
    </button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--secondary">
      Satellite
    </button>
  </li>
</ul>

Guidance

When to use the segmented button group

  • 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 guidance

  • 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".
  • Use aria-label to give the buttons a useful name. Some contexts may require additional context provided to screen readers.
  • Use the <button type="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.

Using the segmented button group

  • Buttons inside of a button group follow the same guidelines as the button component.
  • Button groups support any style and size.
  • 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

  • Package usage: @forward "usa-button-group";
  • Dependencies: usa-button

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-05-31 3.8.1
  • Styles
 No

Improved styles for nested button groups. Now, nested button groups should match the height of their parents. More information: uswds#5885

2024-03-11 3.8.0
  • Styles
 No

Improved the appearance of button groups when text wraps to multiple lines. Now, every button in the group will be the same height. More information: uswds#5657

2022-08-05 3.1.0
  • Accessibility
  • Styles
 No

Styled aria-disabled to match disabled. Now disabled styling is applied whether you use disabled (disabled and hidden from screen readers) or aria-disabled (disabled and visible to screen readers). More information: uswds#4783

2022-08-05 3.1.0
  • JavaScript
  • Markup
 Breaking

Breaking Added type="button" to all non-form buttons to prevent default submit behaviors. This allowed us to remove preventDefault() from the relevant component JavaScript. More information: uswds#4695

2022-08-05 3.1.0
  • Styles
 No

Updated the alignment of unstyled buttons in a button group. More information: uswds#4812

2022-04-28 N/A
  • Guidance
 No

Updated package name to usa-button-group. More information: uswds-site#1538

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656