# Button Group A button group arranges related buttons and can manage their selection, density and overflow. **Example: A standard button group of three buttons** ```html Left Center Right ``` ## Usage guidelines * **Choose standard or connected.** In a standard group, buttons respond to the one that is pressed; a [connected group](#connected) joins them into one control. * **Keep buttons alike.** Use the same size and shape for every button, and mix sizes only for hero moments. * **Group related buttons.** Mix colors and widths to emphasize what matters and to group related actions. * **Let it adapt.** On narrow screens, trailing buttons can collapse into an [overflow menu](#overflow-menu). This component is new in [M3 Expressive](https://m3.material.io/blog/building-with-m3-expressive). ## Anatomy A button group holds `md-gb-button` elements, each with an optional icon. **Example: A button group of three buttons with an icon and a label** ```html content_cut Cut content_copy Copy content_paste Paste ``` ## Examples ### Connected Set `variant="connected"` for buttons that sit together as a single control. **Example: A connected button group** ```html Day Week Month ``` ### Selection Set `selection` to `single` or `multiple` and give each button a `value`. Add `required` to keep one selected in a single-select group. A group fires `input` and `change` when selection changes. **Example: A single-select button group with Week selected** ```html Day Week Month ``` ### Icons Buttons in a group can be icon-only. Give each one an `aria-label`. **Example: A button group of icon buttons** ```html thumb_up favorite share ``` ### Density Set `density` from 0 (default) to -3 to make the buttons shorter. Touch targets stay 48px. **Example: A button group with density -2** ```html Left Center Right ``` ### Overflow menu Add `overflow-menu` to collapse the buttons that don't fit into a menu at the trailing edge. Choosing a menu entry clicks the original button. **Example: A button group with an overflow menu in a narrow container** ```html Copy Paste Cut Delete ``` ## Accessibility * The group does not need a label of its own, but a name such as `aria-label="Text alignment"` helps when the buttons form a set. * Label each button as you would a [button](/material-web/3.0/components/button/); icon-only buttons need `aria-label`. * Tab enters the group, Arrow keys move between buttons, and Enter or Space activates the focused button. ## API reference ### <md-gb-button-group> A Material Design button group. #### Properties | Property | Attribute | Type | Default | | --- | --- | --- | --- | | density
The density of the buttons inside, from 0 (default) to -3. Each step down removes 4px from the buttons' height (button-groups.md: "Button groups adapt to the height of the buttons inside, including when density is applied"); touch targets stay 48px. A button's own non-zero density wins. Values are clamped to that range. | density | Density | | | disabled
Whether the button group is disabled. | disabled | boolean | false | | overflowMenu
Whether the buttons at the trailing edge that do not fit collapse into a trailing overflow menu, and come back when the group has room again (button-groups.md, Adaptive design: "Buttons at the trailing edge of the button group can be customized to collapse into an overflow menu at smaller breakpoints, and become visible again at larger sizes."). The group is as wide as its container allows: give it a width, or put it in a narrower container, to make buttons overflow. Choosing a menu entry clicks the original button. | overflow-menu | boolean | false | | required
Whether selection is required in single-select mode. | required | boolean | false | | resizing
How the group and its buttons resize (button-groups.md, Resizing). fixed: every button keeps the width its own size and width give it. flexible: the group fills the width of its container and its buttons grow with it; an icon button does not stretch past its set width, and a button with resizing="fixed" keeps its width. A button with resizing="flexible" in a fixed group grows when the group is given more width. Unset: a connected group is flexible (it spans its surface), a standard group is fixed. | resizing | ButtonGroupResizing | "" | | selection
The selection mode. | selection | ButtonGroupSelection | "none" | | variant
The visual variant of the button group. | variant | ButtonGroupVariant | "standard" | #### Slots | Slot | Description | | --- | --- | | default | Used to display buttons. | | overflow | Replaces the default overflow button (see overflowMenu). | #### Events | Event | Description | | --- | --- | | change
Event | Fired when selection changes. | | input
InputEvent | Fired when selection changes. | #### CSS custom properties | Property | Description | | --- | --- | | --between-space | | | --density-step | Button height removed per density step. | | --inner-corner-size | | | --motion-spring-fast-spatial | | | --motion-spring-fast-spatial-duration | | | --outer-corner-size | | | --outer-corner-square-size | | | --pressed-inner-corner-size | | | --pressed-item-width-multiplier | |