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.

Component Preview

Back

Component Code


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

Segmented Button Group

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

Component Preview

Primary

Secondary

Accent Cool

Accent Warm

Base

Outline

Outline Inverse

Big

Component Code


<!-- Primary Segmented -->
<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">Satellite</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button">Hybrid</button>
  </li>
</ul>

<!-- Secondary Segmented -->
<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 usa-button--outline">Satellite</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--secondary usa-button--outline">Hybrid</button>
  </li>
</ul>

<!-- Accent Cool Segmented -->
<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--outline">Satellite</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--outline">Hybrid</button>
  </li>
</ul>

<!-- Accent Warm Segmented -->
<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--outline">Satellite</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--outline">Hybrid</button>
  </li>
</ul>

<!-- Base Segmented -->
<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--outline">Satellite</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--outline">Hybrid</button>
  </li>
</ul>

<!-- Outline Segmented -->
<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">Satellite</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--outline">Hybrid</button>
  </li>
</ul>

<!-- Outline Inverse Segmented (on dark background) -->
<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">Satellite</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--outline usa-button--inverse">Hybrid</button>
  </li>
</ul>

<!-- Big Segmented -->
<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 usa-button--outline">Satellite</button>
  </li>
  <li class="usa-button-group__item">
    <button type="button" class="usa-button usa-button--big usa-button--outline">Hybrid</button>
  </li>
</ul>

Guidance

When to use the default button group

Actions have a contextual relationship. For example, when a form has both a primary and alternative action.

Stepping through linear content. Buttons can be used for directional navigation like "Back," "Next," "Continue," "Skip," or "Cancel."

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

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.
If there are more than three segmented 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 burden of choice.: Try not to present the user with too many options.
Avoid ambiguity of current state.: Make sure current states are clearly communicated and understood in segmented button groups.
Use short, descriptive button labels.: Keep button labels concise and action-oriented.
Don't mix differently-sized buttons.: Don't mix differently-sized buttons (like a default button and a big button) in the same group.

Accessibility guidance

Convey relationship.: If not using a list element, give the parent element role="group" 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 element.: Use <button type="button">. Don't use <a> or <span> because screen readers won't know it's a usable button.

Using the button group component

Buttons follow the same guidelines as the button component.: Buttons inside of a button group follow the same guidelines as the button component.
Button groups support any style and size.: Works with outline, secondary, inverse, accent-cool, accent-warm, base, big, and unstyled button variants.
Use flexbox utilities for layout control.: The default button group displays as a column on smaller screens. Use flex-row utility for row layout on all screens, order for reordering, and flex-justify for button justification.

USWDS Documentation

For more guidance, view the USWDS Button Group Component Documentation.

Settings

This component has no configurable settings. See the USWDS documentation for additional customization options.

Variants

Variant	Description
`.usa-button-group`	Default button group container.
`.usa-button-group__item`	Individual button wrapper element.
`.usa-button-group--segmented`	Segmented variant with connected buttons.