Segmented button

A row of two to five options for choosing one or several of them.

Category: Actions
API status: Stable
Compose APIs: SingleChoiceSegmentedButtonRow, MultiChoiceSegmentedButtonRow, SegmentedButton, SegmentedButtonDefaults
Interactive page: https://m3e.ljzapps.app/#components/segmented-button

When to use

Segmented buttons help people select options, switch views or sort elements. Use single choice when exactly one option applies and multi choice when any number can be active.

Material 3 Expressive recommends connected button groups for new designs. The segmented button remains available and is not deprecated.

Playground

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

Examples

Single choice

val options = listOf("Day", "Week", "Month")
var selected by rememberSaveable { mutableIntStateOf(0) }

SingleChoiceSegmentedButtonRow {
    options.forEachIndexed { index, label ->
        SegmentedButton(
            selected = selected == index,
            onClick = { selected = index },
            shape = SegmentedButtonDefaults.itemShape(index, options.size),
        ) {
            Text(label)
        }
    }
}

Multiple choice

val options = listOf("Bold", "Italic", "Underline")
var checked by remember { mutableStateOf(setOf<Int>()) }

MultiChoiceSegmentedButtonRow {
    options.forEachIndexed { index, label ->
        SegmentedButton(
            checked = index in checked,
            onCheckedChange = { isChecked ->
                checked = if (isChecked) checked + index else checked - index
            },
            shape = SegmentedButtonDefaults.itemShape(index, options.size),
        ) {
            Text(label)
        }
    }
}

Parameters

Name	Type	Default	Description
`selected / checked`	`Boolean`		Whether the segment is active.
`shape`	`Shape`		Use SegmentedButtonDefaults.itemShape(index, count).
`icon`	`@Composable () -> Unit`	`SegmentedButtonDefaults.Icon(selected)`	Leading icon, by default a check mark when selected.
`colors`	`SegmentedButtonColors`	`SegmentedButtonDefaults.colors()`	Colors per state.

Guidelines

Do:

Use two to five segments.
Show the selection state with more than color.

Don't:

Do not use for navigation between pages.
Do not mix text and icon-only segments.

Accessibility

Single choice rows expose the radio group semantics, multi choice rows expose checkboxes.
Keep labels short enough to stay on one line at 200 percent font scale.