ToggleButton

Composable Component

Toggle button is a toggleable button that switches between primary and tonal colors depending on checked's value. It also morphs between the three shapes provided in shapes depending on the state of the interaction with the toggle button as long as the three shapes provided our CornerBasedShapes. If a shape in shapes isn't a CornerBasedShape, then toggle button will toggle between the ToggleButtonShapes according to user interaction.

Common

@Composable
@ExperimentalMaterial3ExpressiveApi
fun ToggleButton(
    checked: Boolean,
    onCheckedChange: (Boolean) -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    shapes: ToggleButtonShapes = ToggleButtonDefaults.shapesFor(ButtonDefaults.MinHeight),
    colors: ToggleButtonColors = ToggleButtonDefaults.toggleButtonColors(),
    elevation: ButtonElevation? = ButtonDefaults.buttonElevation(),
    border: BorderStroke? = null,
    contentPadding: PaddingValues = ButtonDefaults.contentPaddingFor(ButtonDefaults.MinHeight),
    interactionSource: MutableInteractionSource? = null,
    content: @Composable RowScope.() -> Unit,
)

Parameters


checked	whether the toggle button is toggled on or off.
onCheckedChange	called when the toggle button is clicked.
modifier	the `Modifier` to be applied to the toggle button.
enabled	controls the enabled state of this toggle button. When `false`, this component will not respond to user input, and it will appear visually disabled and disabled to accessibility services.
shapes	the `ToggleButtonShapes` that the toggle button will morph between depending on the user's interaction with the toggle button.
colors	`ToggleButtonColors` that will be used to resolve the colors used for this toggle button in different states. See `ToggleButtonDefaults.toggleButtonColors`.
elevation	`ButtonElevation` used to resolve the elevation for this button in different states. This controls the size of the shadow below the button. See `ButtonElevation.shadowElevation`. Additionally, when the container color is `ColorScheme.surface`, this controls the amount of primary color applied as an overlay.
border	the border to draw around the container of this toggle button.
contentPadding	the spacing values to apply internally between the container and the content
interactionSource	an optional hoisted `MutableInteractionSource` for observing and emitting `Interaction`s for this toggle button. You can use this to change the toggle button's appearance or preview the toggle button in different states. Note that if `null` is provided, interactions will still happen internally.
content	The content displayed on the toggle button, expected to be text, icon or image.

Code Examples

ToggleButtonSample

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Preview
@Composable
fun ToggleButtonSample() {
    var checked by remember { mutableStateOf(false) }
    ToggleButton(checked = checked, onCheckedChange = { checked = it }) { Text("Button") }
}

ToggleButtonWithIconSample

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Preview
@Composable
fun ToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    ElevatedToggleButton(checked = checked, onCheckedChange = { checked = it }) {
        Icon(
            if (checked) Icons.Filled.Edit else Icons.Outlined.Edit,
            contentDescription = "Localized description",
            modifier = Modifier.size(ButtonDefaults.IconSize),
        )
        Spacer(Modifier.size(ButtonDefaults.IconSpacing))
        Text("Edit")
    }
}

XSmallToggleButtonWithIconSample

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Preview
@Composable
fun XSmallToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    val size = ButtonDefaults.ExtraSmallContainerHeight
    ToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        modifier = Modifier.heightIn(size),
        shapes = ToggleButtonDefaults.shapesFor(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size),
    ) {
        Icon(
            if (checked) Icons.Filled.Edit else Icons.Outlined.Edit,
            contentDescription = "Localized description",
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label")
    }
}

MediumToggleButtonWithIconSample

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Preview
@Composable
fun MediumToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    val size = ButtonDefaults.MediumContainerHeight
    ToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        modifier = Modifier.heightIn(size),
        shapes = ToggleButtonDefaults.shapesFor(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size),
    ) {
        Icon(
            if (checked) Icons.Filled.Edit else Icons.Outlined.Edit,
            contentDescription = "Localized description",
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

LargeToggleButtonWithIconSample

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Preview
@Composable
fun LargeToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    val size = ButtonDefaults.LargeContainerHeight
    ToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        modifier = Modifier.heightIn(size),
        shapes = ToggleButtonDefaults.shapesFor(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size),
    ) {
        Icon(
            if (checked) Icons.Filled.Edit else Icons.Outlined.Edit,
            contentDescription = "Localized description",
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

XLargeToggleButtonWithIconSample

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Preview
@Composable
fun XLargeToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    val size = ButtonDefaults.ExtraLargeContainerHeight
    ToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        modifier = Modifier.heightIn(size),
        shapes = ToggleButtonDefaults.shapesFor(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size),
    ) {
        Icon(
            if (checked) Icons.Filled.Edit else Icons.Outlined.Edit,
            contentDescription = "Localized description",
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

SquareToggleButtonSample

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Preview
@Composable
fun SquareToggleButtonSample() {
    var checked by remember { mutableStateOf(false) }
    val shapes =
        ToggleButtonShapes(
            shape = ToggleButtonDefaults.squareShape,
            pressedShape = ToggleButtonDefaults.pressedShape,
            checkedShape = ToggleButtonDefaults.roundShape,
        )
    ToggleButton(checked = checked, onCheckedChange = { checked = it }, shapes = shapes) {
        Text("Button")
    }
}