A button group is a row of joined System buttons for choosing between two to four short options. The selected button has a black 12% fill.
Every example on this page is the real component, not a picture.
Joined System buttons that work as a toggle group. Click one to select it. This is the control the playgrounds on this site use.
A button group is a row of joined System buttons for choosing between two to four short options. The selected button has a black 12% fill.
It is a toggle group: your script sets aria-pressed on the chosen button. It is the control the playgrounds on this site use, and it fits a toolbar or a filter row. It is not the sliding pill (see Pill segment control).
This documentation has three pages. Examples & Guidelines (this page) shows when and how to use a button group. Specifications holds the values: tokens, sizes, measurements, states and requirements. Code shows how to add one to a page.
Use a button group to pick one of two to four short options in a toolbar, a filter row or a playground. Use it to:
The group never wraps onto a second row, and it is never made smaller to fit. With more options, or when the group does not fit its container, show a select with the same options instead.
The group shows all its options on one row. Short labels keep it narrow; long labels make it wider than its container.
| The user… | Use |
|---|---|
| picks one of 2–4 short options on a toolbar or in a playground | Button group |
| switches the main view of a surface with a sliding pill | Pill segment control |
| picks one of many options | Select |
| picks one and submits | Radio |
| goes to another page | Tabs or a link |
aria-label or a visible label.aria-pressed on the selected button.button-group.css.role="group" row of buttons. It is inline-flex and never wider than its parent.aria-pressed="true": a black 12% fill and the same frame.margin-left: -1px.Two to four short options on one row. The group never wraps. With more options, use a select.
The button group has one size: Small System buttons, 32px high on mobile and 40px from 769px. The tablet range (640 to 768px) uses the mobile size. Measurements are under Sizes in Specifications.
The group is as wide as its buttons and never wider than its parent. Buttons share their 1px frame. When the group does not fit, for example in a narrow controls column, show a select with the same options and keep the two in sync.
A group sits at the start of its row (align-self: flex-start). In a toolbar put the visible label before it.
A light frame, an uppercase label and a black 12% fill for the selected button. Token names and values are under Design Tokens in Specifications.
One button is selected at a time. Your script sets aria-pressed; the CSS does not toggle it.
Hover darkens the frame to border-hover and, when the button is not selected, adds the fill. The focus ring is 2px with a 2px gap and shows on keyboard use only (body.keyboard-nav). All states are listed under States in Specifications.
A disabled button is not focusable. Its label and frame use the disabled tokens.
The frame and the fill change over 100ms. Values are under Motion in Specifications.
All requirements are listed under Accessibility Requirements in Specifications.
Tab moves between the buttons. Enter or Space chooses the focused one. The focus ring shows on keyboard use only.
The group is a role="group" with an aria-label or aria-labelledby. Each button is a real <button type="button"> with aria-pressed, so the chosen one is announced as pressed.