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
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.
The default button group arranges each button as a separate element with a gap between them. On mobile devices, the buttons are arranged vertically.
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.
- Avoid burden of choice. Try not to present the user with too many options.
- 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
Segmented button groups display a set of discrete buttons in a row as a single element.
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.
- Avoid ambiguity of current state. Make sure current states are clearly communicated and understood.
aria-labelto 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.
- 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.