Button group

Arranges related buttons and moves the ones that do not fit into an overflow menu.

Category: Actions
API status: Expressive
Compose APIs: ButtonGroup, ButtonGroupDefaults.OverflowIndicator, clickableItem, toggleableItem, customItem
Interactive page: https://m3e.ljzapps.app/#components/button-group

When to use

ButtonGroup lays out clickable and toggleable items in a row. Items grow slightly when pressed and push their neighbors aside. When the available width is too small, the remaining items move into an overflow menu.

Use items through the group scope instead of placing buttons directly. That lets the group measure every item, decide what fits and build the overflow menu from the same data.

Playground

The interactive page has a playground with live property controls for this component and generated code.

Examples

Overflow

Narrow the window or use the playground to see items move into the menu.

var starred by rememberSaveable { mutableStateOf(false) }

ButtonGroup(
    modifier = Modifier.width(360.dp),
    overflowIndicator = { menuState -> ButtonGroupDefaults.OverflowIndicator(menuState) },
) {
    clickableItem(
        onClick = {},
        label = "Edit",
        icon = { Icon(Icons.Rounded.Edit, contentDescription = null) },
    )
    toggleableItem(
        checked = starred,
        label = "Star",
        onCheckedChange = { starred = it },
        icon = { Icon(Icons.Rounded.Star, contentDescription = null) },
    )
    clickableItem(
        onClick = {},
        label = "Share",
        icon = { Icon(Icons.Rounded.Share, contentDescription = null) },
    )
    clickableItem(
        onClick = {},
        label = "Delete",
        icon = { Icon(Icons.Rounded.Delete, contentDescription = null) },
    )
}

Parameters

Name	Type	Default	Description
`overflowIndicator`	`@Composable (ButtonGroupMenuState) -> Unit`		Shown when items do not fit. Use ButtonGroupDefaults.OverflowIndicator.
`modifier`	`Modifier`	`Modifier`	Constrain the width to control when overflow happens.
`expandedRatio`	`Float`	`0.15f`	How much a pressed item grows.
`horizontalArrangement`	`Arrangement.Horizontal`	`ButtonGroupDefaults.HorizontalArrangement`	Spacing between items.
`verticalAlignment`	`Alignment.Vertical`	`Alignment.Top`	Cross axis alignment of items.
`content`	`ButtonGroupScope.() -> Unit`		Declare items with clickableItem, toggleableItem and customItem.

Guidelines

Do:

Group actions that are closely related.
Put the most important actions first, they overflow last.

Don't:

Do not mix unrelated actions in one group.
Do not rely on overflow for primary actions on small screens.

Accessibility

Every item needs a label. The label doubles as the menu text when the item overflows.
Icon-only items still need a label string, which is announced by screen readers.
The overflow indicator is an icon button with a built-in content description.