# Toggle button

> A button that keeps a selected state and morphs between round and square when it changes.

- Category: Actions
- API status: Expressive
- Compose APIs: `ToggleButton`, `TonalToggleButton`, `ElevatedToggleButton`, `OutlinedToggleButton`, `ToggleButtonDefaults`
- Interactive page: https://m3e.ljzapps.app/#components/toggle-button

## When to use

Use a toggle button to switch a single option on or off, such as a filter or a favorite. The shape is part of the state: unselected buttons are round, selected buttons turn square.

Pick the shapes for the height with ToggleButtonDefaults.shapesFor so the pressed and checked shapes match the size.

## Playground

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

## Examples

### Types

All four types, toggle each one.

```kotlin
var a by rememberSaveable { mutableStateOf(true) }
var b by rememberSaveable { mutableStateOf(false) }
var c by rememberSaveable { mutableStateOf(false) }
var d by rememberSaveable { mutableStateOf(false) }

ToggleButton(checked = a, onCheckedChange = { a = it }) { Text("Filled") }
TonalToggleButton(checked = b, onCheckedChange = { b = it }) { Text("Tonal") }
ElevatedToggleButton(checked = c, onCheckedChange = { c = it }) { Text("Elevated") }
OutlinedToggleButton(checked = d, onCheckedChange = { d = it }) { Text("Outlined") }
```

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `checked` | `Boolean` |  | Whether the button is selected. |
| `onCheckedChange` | `(Boolean) -> Unit` |  | Called with the requested new state. |
| `shapes` | `ToggleButtonShapes` | `ToggleButtonDefaults.shapesFor(MinHeight)` | Resting, pressed and checked shapes. The button morphs between them. |
| `colors` | `ToggleButtonColors` | `toggleButtonColors()` | Container and content colors for checked and unchecked states. |
| `contentPadding` | `PaddingValues` | `contentPaddingFor(MinHeight)` | Padding that matches the height. |

## Guidelines

Do:
- Use for binary options that apply immediately.
- Keep the label constant, the state shows the change.

Don't:
- Do not change the label from On to Off.
- Do not use it for one-time actions.

## Accessibility

- The button exposes a toggleable state and the Checkbox-like role, so screen readers announce selected or not selected.
- Do not communicate the state with the shape alone. The color difference is part of the default colors.

## Related components

- [Connected button group](https://m3e.ljzapps.app/docs/components/connected-button-group.md)
- [Buttons](https://m3e.ljzapps.app/docs/components/button.md)
- [Icon button](https://m3e.ljzapps.app/docs/components/icon-button.md)