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.

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.