# 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

```kotlin
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

```kotlin
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.

## Related components

- [Connected button group](https://m3e.ljzapps.app/docs/components/connected-button-group.md)
- [Toggle button](https://m3e.ljzapps.app/docs/components/toggle-button.md)
- [Chips](https://m3e.ljzapps.app/docs/components/chips.md)