androidx.compose.foundation.selection

Extension functions summary

Modifier
Modifier.selectable(
    selected: Boolean,
    enabled: Boolean,
    role: Role?,
    onClick: () -> Unit
)

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.

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

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.

Cmn
Modifier

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

Cmn
Modifier
Modifier.toggleable(
    value: Boolean,
    enabled: Boolean,
    role: Role?,
    onValueChange: (Boolean) -> Unit
)

Configure component to make it toggleable via input and accessibility events

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

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

Cmn
Modifier
Modifier.triStateToggleable(
    state: ToggleableState,
    enabled: Boolean,
    role: Role?,
    onClick: () -> Unit
)

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

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

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

Cmn

Extension functions

selectable

fun Modifier.selectable(
    selected: Boolean,
    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

This version has no MutableInteractionSource or Indication parameters, the default indication from LocalIndication will be used. To specify MutableInteractionSource or Indication, use the other overload.

If you are only creating this selectable modifier inside composition, consider using the other overload and explicitly passing LocalIndication.current for improved performance. For more information see the documentation on the other overload.

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

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 }
                    )
            )
        }
    }
}
Parameters
selected: Boolean

whether or not this item is selected in a mutually exclusion set

enabled: Boolean = true

whether or not this selectable will handle input events and appear enabled from a semantics perspective

role: Role? = null

the type of user interface element. Accessibility services might use this to describe the element or do customizations

onClick: () -> Unit

callback to invoke when this item is clicked

selectable

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

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 }
                    )
            )
        }
    }
}
Parameters
selected: Boolean

whether or not this item is selected in a mutually exclusion set

interactionSource: MutableInteractionSource?

MutableInteractionSource that will be used to dispatch PressInteraction.Press when this selectable is pressed. If null, an internal MutableInteractionSource will be created if needed.

indication: Indication?

indication to be shown when the modified element is pressed. By default, the indication from LocalIndication will be used. Set to null to show no indication, or current value from LocalIndication to show theme default

enabled: Boolean = true

whether or not this selectable will handle input events and appear enabled from a semantics perspective

role: Role? = null

the type of user interface element. Accessibility services might use this to describe the element or do customizations

onClick: () -> Unit

callback to invoke when this item is clicked

selectableGroup

fun Modifier.selectableGroup(): Modifier

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

See also
selectableGroup

toggleable

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

Configure component to make it toggleable via input and accessibility events

This version has no MutableInteractionSource or Indication parameters, the default indication from LocalIndication will be used. To specify MutableInteractionSource or Indication, use the other overload.

If you are only creating this toggleable modifier inside composition, consider using the other overload and explicitly passing LocalIndication.current for improved performance. For more information see the documentation on the other overload.

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

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()
)
Parameters
value: Boolean

whether Toggleable is on or off

enabled: Boolean = true

whether or not this toggleable will handle input events and appear enabled for semantics purposes

role: Role? = null

the type of user interface element. Accessibility services might use this to describe the element or do customizations

onValueChange: (Boolean) -> Unit

callback to be invoked when toggleable is clicked, therefore the change of the state in requested.

See also
triStateToggleable

if you require support for an indeterminate state.

toggleable

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

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()
)
Parameters
value: Boolean

whether Toggleable is on or off

interactionSource: MutableInteractionSource?

MutableInteractionSource that will be used to dispatch PressInteraction.Press when this toggleable is pressed. If null, an internal MutableInteractionSource will be created if needed.

indication: Indication?

indication to be shown when modified element is pressed. Be default, indication from LocalIndication will be used. Pass null to show no indication, or current value from LocalIndication to show theme default

enabled: Boolean = true

whether or not this toggleable will handle input events and appear enabled for semantics purposes

role: Role? = null

the type of user interface element. Accessibility services might use this to describe the element or do customizations

onValueChange: (Boolean) -> Unit

callback to be invoked when toggleable is clicked, therefore the change of the state in requested.

See also
triStateToggleable

if you require support for an indeterminate state.

triStateToggleable

fun Modifier.triStateToggleable(
    state: ToggleableState,
    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.

This version has no MutableInteractionSource or Indication parameters, the default indication from LocalIndication will be used. To specify MutableInteractionSource or Indication, use the other overload.

If you are only creating this triStateToggleable modifier inside composition, consider using the other overload and explicitly passing LocalIndication.current for improved performance. For more information see the documentation on the other overload.

import androidx.compose.foundation.selection.triStateToggleable
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

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()
)
Parameters
state: ToggleableState

current value for the component

enabled: Boolean = true

whether or not this triStateToggleable will handle input events and appear enabled for semantics purposes

role: Role? = null

the type of user interface element. Accessibility services might use this to describe the element or do customizations

onClick: () -> Unit

will be called when user clicks the toggleable.

See also
toggleable

if you want to support only two states: on and off

triStateToggleable

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.triStateToggleable
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

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()
)
Parameters
state: ToggleableState

current value for the component

interactionSource: MutableInteractionSource?

MutableInteractionSource that will be used to dispatch PressInteraction.Press when this triStateToggleable is pressed. If null, an internal MutableInteractionSource will be created if needed.

indication: Indication?

indication to be shown when modified element is pressed. Be default, indication from LocalIndication will be used. Pass null to show no indication, or current value from LocalIndication to show theme default

enabled: Boolean = true

whether or not this triStateToggleable will handle input events and appear enabled for semantics purposes

role: Role? = null

the type of user interface element. Accessibility services might use this to describe the element or do customizations

onClick: () -> Unit

will be called when user clicks the toggleable.

See also
toggleable

if you want to support only two states: on and off