androidx.compose.foundation.selection

fun Modifier.selectable(
    selected: Boolean,
    enabled: Boolean = true,
    role: Role? = null,
    interactionSource: MutableInteractionSource? = null,
    onClick: () -> Unit
): Modifier

Configure component to be selectable, usually as a part of a mutually exclusive group, where only one item can be selected at any point in time. A typical example of mutually exclusive set is a RadioGroup or a row of Tabs. To ensure correct accessibility behavior, make sure to pass Modifier.selectableGroup modifier into the RadioGroup or the row.

If you want to make an item support on/off capabilities without being part of a set, consider using Modifier.toggleable

This overload will use the Indication from LocalIndication. Use the other overload to explicitly provide an Indication instance. Note that this overload only supports IndicationNodeFactory instances provided through LocalIndication - it is strongly recommended to migrate to IndicationNodeFactory, but you can use the other overload if you still need to support Indication instances that are not IndicationNodeFactory.

If interactionSource is null, an internal MutableInteractionSource will be lazily created only when needed. This reduces the performance cost of selectable during composition, as creating the indication can be delayed until there is an incoming androidx.compose.foundation.interaction.Interaction. If you are only passing a remembered MutableInteractionSource and you are never using it outside of selectable, it is recommended to instead provide null to enable lazy creation. If you need the Indication to be created eagerly, provide a remembered MutableInteractionSource.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.selection.selectable
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

val option1 = Color.Red
val option2 = Color.Blue
var selectedOption by remember { mutableStateOf(option1) }
Column {
    Text("Selected: $selectedOption")
    Row {
        listOf(option1, option2).forEach { color ->
            val selected = selectedOption == color
            Box(
                Modifier.size(100.dp)
                    .background(color = color)
                    .selectable(selected = selected, onClick = { selectedOption = color })
            )
        }
    }
}

fun Modifier.selectable(
    selected: Boolean,
    interactionSource: MutableInteractionSource?,
    indication: Indication?,
    enabled: Boolean = true,
    role: Role? = null,
    onClick: () -> Unit
): Modifier

Configure component to be selectable, usually as a part of a mutually exclusive group, where only one item can be selected at any point in time. A typical example of mutually exclusive set is a RadioGroup or a row of Tabs. To ensure correct accessibility behavior, make sure to pass Modifier.selectableGroup modifier into the RadioGroup or the row.

If you want to make an item support on/off capabilities without being part of a set, consider using Modifier.toggleable

If interactionSource is null, and indication is an IndicationNodeFactory, an internal MutableInteractionSource will be lazily created along with the indication only when needed. This reduces the performance cost of selectable during composition, as creating the indication can be delayed until there is an incoming androidx.compose.foundation.interaction.Interaction. If you are only passing a remembered MutableInteractionSource and you are never using it outside of selectable, it is recommended to instead provide null to enable lazy creation. If you need indication to be created eagerly, provide a remembered MutableInteractionSource.

If indication is not an IndicationNodeFactory, and instead implements the deprecated Indication.rememberUpdatedInstance method, you should explicitly pass a remembered MutableInteractionSource as a parameter for interactionSource instead of null, as this cannot be lazily created inside selectable.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.selection.selectable
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

val option1 = Color.Red
val option2 = Color.Blue
var selectedOption by remember { mutableStateOf(option1) }
Column {
    Text("Selected: $selectedOption")
    Row {
        listOf(option1, option2).forEach { color ->
            val selected = selectedOption == color
            Box(
                Modifier.size(100.dp)
                    .background(color = color)
                    .selectable(selected = selected, onClick = { selectedOption = color })
            )
        }
    }
}

fun Modifier.selectableGroup(): Modifier

Use this modifier to group a list of selectable items like Tabs or RadioButtons together for accessibility purpose.

fun Modifier.toggleable(
    value: Boolean,
    enabled: Boolean = true,
    role: Role? = null,
    interactionSource: MutableInteractionSource? = null,
    onValueChange: (Boolean) -> Unit
): Modifier

Configure component to make it toggleable via input and accessibility events

This overload will use the Indication from LocalIndication. Use the other overload to explicitly provide an Indication instance. Note that this overload only supports IndicationNodeFactory instances provided through LocalIndication - it is strongly recommended to migrate to IndicationNodeFactory, but you can use the other overload if you still need to support Indication instances that are not IndicationNodeFactory.

If interactionSource is null, an internal MutableInteractionSource will be lazily created only when needed. This reduces the performance cost of toggleable during composition, as creating the indication can be delayed until there is an incoming androidx.compose.foundation.interaction.Interaction. If you are only passing a remembered MutableInteractionSource and you are never using it outside of toggleable, it is recommended to instead provide null to enable lazy creation. If you need the Indication to be created eagerly, provide a remembered MutableInteractionSource.

import androidx.compose.foundation.selection.toggleable
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier

var checked by remember { mutableStateOf(false) }
// content that you want to make toggleable
Text(
    modifier = Modifier.toggleable(value = checked, onValueChange = { checked = it }),
    text = checked.toString(),
)

fun Modifier.toggleable(
    value: Boolean,
    interactionSource: MutableInteractionSource?,
    indication: Indication?,
    enabled: Boolean = true,
    role: Role? = null,
    onValueChange: (Boolean) -> Unit
): Modifier

Configure component to make it toggleable via input and accessibility events.

If interactionSource is null, and indication is an IndicationNodeFactory, an internal MutableInteractionSource will be lazily created along with the indication only when needed. This reduces the performance cost of toggleable during composition, as creating the indication can be delayed until there is an incoming androidx.compose.foundation.interaction.Interaction. If you are only passing a remembered MutableInteractionSource and you are never using it outside of toggleable, it is recommended to instead provide null to enable lazy creation. If you need indication to be created eagerly, provide a remembered MutableInteractionSource.

If indication is not an IndicationNodeFactory, and instead implements the deprecated Indication.rememberUpdatedInstance method, you should explicitly pass a remembered MutableInteractionSource as a parameter for interactionSource instead of null, as this cannot be lazily created inside toggleable.

import androidx.compose.foundation.selection.toggleable
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier

var checked by remember { mutableStateOf(false) }
// content that you want to make toggleable
Text(
    modifier = Modifier.toggleable(value = checked, onValueChange = { checked = it }),
    text = checked.toString(),
)

fun Modifier.triStateToggleable(
    state: ToggleableState,
    enabled: Boolean = true,
    role: Role? = null,
    interactionSource: MutableInteractionSource? = null,
    onClick: () -> Unit
): Modifier

Configure component to make it toggleable via input and accessibility events with three states: On, Off and Indeterminate.

TriStateToggleable should be used when there are dependent Toggleables associated to this component and those can have different values.

This overload will use the Indication from LocalIndication. Use the other overload to explicitly provide an Indication instance. Note that this overload only supports IndicationNodeFactory instances provided through LocalIndication - it is strongly recommended to migrate to IndicationNodeFactory, but you can use the other overload if you still need to support Indication instances that are not IndicationNodeFactory.

If interactionSource is null, an internal MutableInteractionSource will be lazily created only when needed. This reduces the performance cost of triStateToggleable during composition, as creating the indication can be delayed until there is an incoming androidx.compose.foundation.interaction.Interaction. If you are only passing a remembered MutableInteractionSource and you are never using it outside of triStateToggleable, it is recommended to instead provide null to enable lazy creation. If you need the Indication to be created eagerly, provide a remembered MutableInteractionSource.

import androidx.compose.foundation.selection.toggleable
import androidx.compose.foundation.selection.triStateToggleable
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.state.ToggleableState

var checked by remember { mutableStateOf(ToggleableState.Indeterminate) }
// content that you want to make toggleable
Text(
    modifier =
        Modifier.triStateToggleable(
            state = checked,
            onClick = {
                checked =
                    if (checked == ToggleableState.On) ToggleableState.Off
                    else ToggleableState.On
            },
        ),
    text = checked.toString(),
)

fun Modifier.triStateToggleable(
    state: ToggleableState,
    interactionSource: MutableInteractionSource?,
    indication: Indication?,
    enabled: Boolean = true,
    role: Role? = null,
    onClick: () -> Unit
): Modifier

Configure component to make it toggleable via input and accessibility events with three states: On, Off and Indeterminate.

TriStateToggleable should be used when there are dependent Toggleables associated to this component and those can have different values.

If interactionSource is null, and indication is an IndicationNodeFactory, an internal MutableInteractionSource will be lazily created along with the indication only when needed. This reduces the performance cost of triStateToggleable during composition, as creating the indication can be delayed until there is an incoming androidx.compose.foundation.interaction.Interaction. If you are only passing a remembered MutableInteractionSource and you are never using it outside of triStateToggleable, it is recommended to instead provide null to enable lazy creation. If you need indication to be created eagerly, provide a remembered MutableInteractionSource.

If indication is not an IndicationNodeFactory, and instead implements the deprecated Indication.rememberUpdatedInstance method, you should explicitly pass a remembered MutableInteractionSource as a parameter for interactionSource instead of null, as this cannot be lazily created inside triStateToggleable.

import androidx.compose.foundation.selection.toggleable
import androidx.compose.foundation.selection.triStateToggleable
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.state.ToggleableState

var checked by remember { mutableStateOf(ToggleableState.Indeterminate) }
// content that you want to make toggleable
Text(
    modifier =
        Modifier.triStateToggleable(
            state = checked,
            onClick = {
                checked =
                    if (checked == ToggleableState.On) ToggleableState.Off
                    else ToggleableState.On
            },
        ),
    text = checked.toString(),
)