Stepper

Stepper allows users to make a selection from a range of values. It's a full-screen control with increase button on the top, decrease button on the bottom and a slot (expected to have either Text or Chip) in the middle. Value can be increased and decreased by clicking on the increase and decrease buttons. Buttons can have custom icons - decreaseIcon and increaseIcon. Step value is calculated as the difference between min and max values divided by steps+1. Stepper itself doesn't show the current value but can be displayed via the content slot or PositionIndicator if required. If value is not equal to any step value, then it will be coerced to the closest step value. However, the value itself will not be changed and onValueChange in this case will not be triggered.

Android
@Composable
public fun Stepper(
    value: Float,
    onValueChange: (Float) -> Unit,
    steps: Int,
    decreaseIcon: @Composable () -> Unit,
    increaseIcon: @Composable () -> Unit,
    modifier: Modifier = Modifier,
    valueRange: ClosedFloatingPointRange<Float> = 0f..(steps + 1).toFloat(),
    backgroundColor: Color = MaterialTheme.colors.background,
    contentColor: Color = contentColorFor(backgroundColor),
    iconColor: Color = contentColor,
    enableRangeSemantics: Boolean = true,
    content: @Composable BoxScope.() -> Unit,
)

Parameters
value Current value of the Stepper. If outside of valueRange provided, value will be coerced to this range.
onValueChange Lambda in which value should be updated
steps Specifies the number of discrete values, excluding min and max values, evenly distributed across the whole value range. Must not be negative. If 0, stepper will have only min and max values and no steps in between
decreaseIcon A slot for an icon which is placed on the decrease (bottom) button
increaseIcon A slot for an icon which is placed on the increase (top) button
modifier Modifiers for the Stepper layout
valueRange Range of values that Stepper value can take. Passed value will be coerced to this range
backgroundColor Color representing the background color for the stepper.
contentColor Color representing the color for content in the middle.
iconColor Icon tint Color which used by increaseIcon and decreaseIcon that defaults to contentColor, unless specifically overridden.
enableRangeSemantics Boolean to decide if range semantics should be enabled. Set to false to disable default stepper range semantics. Alternatively to customize semantics set this value as false and chain new semantics to the modifier.
content Content body for the Stepper.
Android
@Composable
public fun Stepper(
    value: Int,
    onValueChange: (Int) -> Unit,
    valueProgression: IntProgression,
    decreaseIcon: @Composable () -> Unit,
    increaseIcon: @Composable () -> Unit,
    modifier: Modifier = Modifier,
    backgroundColor: Color = MaterialTheme.colors.background,
    contentColor: Color = contentColorFor(backgroundColor),
    iconColor: Color = contentColor,
    enableRangeSemantics: Boolean = true,
    content: @Composable BoxScope.() -> Unit,
)

Parameters
value Current value of the Stepper. If outside of valueProgression provided, value will be coerced to this range.
onValueChange Lambda in which value should be updated
valueProgression Progression of values that Stepper value can take. Consists of rangeStart, rangeEnd and step. Range will be equally divided by step size
decreaseIcon A slot for an icon which is placed on the decrease (bottom) button
increaseIcon A slot for an icon which is placed on the increase (top) button
modifier Modifiers for the Stepper layout
backgroundColor Color representing the background color for the stepper.
contentColor Color representing the color for content in the middle.
iconColor Icon tint Color which used by increaseIcon and decreaseIcon that defaults to contentColor, unless specifically overridden.
enableRangeSemantics Boolean to decide if default stepper semantics should be enabled. Set to false to disable default stepper range semantics. Alternatively to customize semantics set this value as false and chain new semantics to the modifier.
content Content body for the Stepper.
Android
Deprecated This overload is provided for backwards compatibility with Compose for Wear OS 1.1. A newer overload is available with an additional enableDefaultSemantics parameter.
@Composable
public fun Stepper(
    value: Float,
    onValueChange: (Float) -> Unit,
    steps: Int,
    decreaseIcon: @Composable () -> Unit,
    increaseIcon: @Composable () -> Unit,
    modifier: Modifier = Modifier,
    valueRange: ClosedFloatingPointRange<Float> = 0f..(steps + 1).toFloat(),
    backgroundColor: Color = MaterialTheme.colors.background,
    contentColor: Color = contentColorFor(backgroundColor),
    iconColor: Color = contentColor,
    content: @Composable BoxScope.() -> Unit,
): Unit

Parameters
value Current value of the Stepper. If outside of valueRange provided, value will be coerced to this range.
onValueChange Lambda in which value should be updated
steps Specifies the number of discrete values, excluding min and max values, evenly distributed across the whole value range. Must not be negative. If 0, stepper will have only min and max values and no steps in between
decreaseIcon A slot for an icon which is placed on the decrease (bottom) button
increaseIcon A slot for an icon which is placed on the increase (top) button
modifier Modifiers for the Stepper layout
valueRange Range of values that Stepper value can take. Passed value will be coerced to this range
backgroundColor Color representing the background color for the stepper.
contentColor Color representing the color for content in the middle.
iconColor Icon tint Color which used by increaseIcon and decreaseIcon that defaults to contentColor, unless specifically overridden.
Android
Deprecated This overload is provided for backwards compatibility with Compose for Wear OS 1.1. A newer overload is available with an additional enableDefaultSemantics parameter.
@Composable
public fun Stepper(
    value: Int,
    onValueChange: (Int) -> Unit,
    valueProgression: IntProgression,
    decreaseIcon: @Composable () -> Unit,
    increaseIcon: @Composable () -> Unit,
    modifier: Modifier = Modifier,
    backgroundColor: Color = MaterialTheme.colors.background,
    contentColor: Color = contentColorFor(backgroundColor),
    iconColor: Color = contentColor,
    content: @Composable BoxScope.() -> Unit,
)

Parameters
value Current value of the Stepper. If outside of valueProgression provided, value will be coerced to this range.
onValueChange Lambda in which value should be updated
valueProgression Progression of values that Stepper value can take. Consists of rangeStart, rangeEnd and step. Range will be equally divided by step size
decreaseIcon A slot for an icon which is placed on the decrease (bottom) button
increaseIcon A slot for an icon which is placed on the increase (top) button
modifier Modifiers for the Stepper layout
backgroundColor Color representing the background color for the stepper.
contentColor Color representing the color for content in the middle.
iconColor Icon tint Color which used by increaseIcon and decreaseIcon that defaults to contentColor, unless specifically overridden.

Code Examples

StepperSample

@Composable
fun StepperSample() {
    var value by remember { mutableStateOf(2f) }
    Stepper(
        value = value,
        onValueChange = { value = it },
        valueRange = 1f..4f,
        increaseIcon = { Icon(StepperDefaults.Increase, "Increase") },
        decreaseIcon = { Icon(StepperDefaults.Decrease, "Decrease") },
        steps = 7,
    ) {
        Text("Value: $value")
    }
}

StepperWithCustomSemanticsSample

@Composable
fun StepperWithCustomSemanticsSample() {
    var value by remember { mutableStateOf(2f) }
    val valueRange = 1f..4f
    val onValueChange = { i: Float -> value = i }
    val steps = 7
    Stepper(
        value = value,
        onValueChange = onValueChange,
        valueRange = valueRange,
        modifier = Modifier.customSemantics(value, true, onValueChange, valueRange, steps),
        increaseIcon = { Icon(StepperDefaults.Increase, "Increase") },
        decreaseIcon = { Icon(StepperDefaults.Decrease, "Decrease") },
        steps = steps,
        enableRangeSemantics = false,
    ) {
        Text("Value: $value")
    }
}

StepperWithIntegerSample

@Composable
fun StepperWithIntegerSample() {
    var value by remember { mutableStateOf(2) }
    Stepper(
        value = value,
        onValueChange = { value = it },
        increaseIcon = { Icon(StepperDefaults.Increase, "Increase") },
        decreaseIcon = { Icon(StepperDefaults.Decrease, "Decrease") },
        valueProgression = 1..10,
    ) {
        Text("Value: $value")
    }
}

StepperWithoutRangeSemanticsSample

@Composable
fun StepperWithoutRangeSemanticsSample() {
    var value by remember { mutableStateOf(2f) }
    Stepper(
        value = value,
        onValueChange = { value = it },
        valueRange = 1f..4f,
        increaseIcon = { Icon(StepperDefaults.Increase, "Increase") },
        decreaseIcon = { Icon(StepperDefaults.Decrease, "Decrease") },
        steps = 7,
        enableRangeSemantics = false,
    ) {
        Text("Value: $value")
    }
}
View all →