Button Groups

Button groups allow users to group related actions or selections. They come in two primary flavors: Standard (spaced) and Connected (segmented).

Introduction

The MD3 Expressive Button Group is a layout component that unifies related actions. It supports two distinct visual styles: Standard, which maintains individual button identities with expressive motion, and Connected (Segmented Buttons), which joins buttons into a single, cohesive unit. This component is ideal for toggling between views, filtering content, or grouping primary actions.

Anatomy

• Container: The wrapper that manages the layout and spacing of the buttons.
• Buttons: The individual interactive elements within the group.
• Dividers (Connected Variant): Thin lines that separate segments within a unified container.
• Active Indicator (Segmented): A visual highlight (often with a checkmark) for the currently selected option.

Variants

Standard Group

Individual buttons placed together with a specific gap. Buttons retain individual identities and feature spring-based shape morphing (border radius changes) on press or selection.

Connected Group (Segmented Buttons)

Buttons are joined together, sharing boundaries. This variant is typically used for selection (e.g., switching between Day, Week, and Month views).

Features

Orientation

Supports both horizontal and vertical layouts.

• Horizontal: Standard layout for action bars and selection segments.
• Vertical: Ideal for toolbars, sidebars, or stacked actions. In Connected mode, the top/bottom corners are rounded while middle buttons remain square.

Expressive Shape Morphing

In standard groups, buttons feature spring-based shape morphing where pressing or selecting a button morphs its corner radius from fully rounded down to a squished/pressed radius.

Full Width Stretching

The fullWidth prop allows the group to expand and fill its container. In horizontal groups, children stretch proportionally (flex-1). In vertical groups, buttons expand to fill the available width.

Note: For dynamic width expansion across dynamic, fixed, and mixed layout modes, see ButtonDistribute.

Icon & Label Behaviors

You can control how icons and labels are displayed based on the selection state using iconBehavior and labelBehavior. This is commonly used in navigation bars to show labels only for the active item.

Usage

Basic Standard Group

import { ButtonGroup, Button } from "@bug-on/m3-expressive";

<ButtonGroup variant="standard">
  <Button>Cancel</Button>
  <Button colorStyle="filled">Save Changes</Button>
</ButtonGroup>

Segmented Buttons for Selection

<ButtonGroup variant="connected" showCheck>
  <Button selected>List View</Button>
  <Button>Grid View</Button>
  <Button>Map View</Button>
</ButtonGroup>

Best Practices

Do

• Group related actions that belong together in the user flow.
• Use Connected (Segmented) buttons for switching between mutually exclusive options.
• Keep the number of buttons in a group between 2 and 5.
• Use consistent button styles (e.g., all Tonal or all Outlined) within a group.

Don't

• Don't group unrelated actions together just to save space.
• Don't use a button group if the actions take the user to completely different parts of the application (use a Menu or Navigation instead).
• Avoid mixing different button heights within the same group.

Accessibility

• Roles: Automatically applies role="group".
• Focus Management: Buttons are individually focusable via Tab.
• Keyboard: Standard button interaction applies. For selection groups, the aria-pressed state is managed.
• Motion: Morphing and selection animations respect prefers-reduced-motion.

API Reference

ButtonGroup