swipeable

Modifier in Material Compose

Enable swipe gestures between a set of predefined states.

To use this, you must provide a map of anchors (in pixels) to states (of type [T]). Note that this map cannot be empty and cannot have two anchors mapped to the same state.

When a swipe is detected, the offset of the [SwipeableState] will be updated with the swipe delta. You should use this offset to move your content accordingly (see Modifier.offsetPx). When the swipe ends, the offset will be animated to one of the anchors and when that anchor is reached, the value of the [SwipeableState] will also be updated to the state corresponding to the new anchor. The target anchor is calculated based on the provided positional [thresholds].

Swiping is constrained between the minimum and maximum anchors. If the user attempts to swipe past these bounds, a resistance effect will be applied by default. The amount of resistance at each edge is specified by the [resistance] config. To disable all resistance, set it to null.

Last updated: 2024-10-22 13:47

Installation

dependencies {
   implementation("androidx.compose.material:material:1.8.0-alpha04")
}

Overloads

@ExperimentalMaterialApi
@Deprecated(SwipeableDeprecation)
fun <T> Modifier.swipeable(
    state: SwipeableState<T>,
    anchors: Map<Float, T>,
    orientation: Orientation,
    enabled: Boolean = true,
    reverseDirection: Boolean = false,
    interactionSource: MutableInteractionSource? = null,
    thresholds: (from: T, to: T) -> ThresholdConfig = { _, _ -> FixedThreshold(56.dp) },
    resistance: ResistanceConfig? = resistanceConfig(anchors.keys),
    velocityThreshold: Dp = VelocityThreshold
)

Parameters

name	description
T	The type of the state.
state	The state of the [swipeable].
anchors	Pairs of anchors and states, used to map anchors to states and vice versa.
thresholds	Specifies where the thresholds between the states are. The thresholds will be used to determine which state to animate to when swiping stops. This is represented as a lambda that takes two states and returns the threshold between them in the form of a [ThresholdConfig]. Note that the order of the states corresponds to the swipe direction.
orientation	The orientation in which the [swipeable] can be swiped.
enabled	Whether this [swipeable] is enabled and should react to the user's input.
reverseDirection	Whether to reverse the direction of the swipe, so a top to bottom swipe will behave like bottom to top, and a left to right swipe will behave like right to left.
interactionSource	Optional [MutableInteractionSource] that will passed on to the internal [Modifier.draggable].
resistance	Controls how much resistance will be applied when swiping past the bounds.
velocityThreshold	The threshold (in dp per second) that the end velocity has to exceed in order to animate to the next state, even if the positional [thresholds] have not been reached.

Code Example

SwipeableSample

@Composable
@OptIn(ExperimentalMaterialApi::class)
fun SwipeableSample() {
    // Draw a slider-like composable consisting of a red square moving along a
    // black background, with three states: "A" (min), "B" (middle), and "C" (max).
    val width = 350.dp
    val squareSize = 50.dp

    val swipeableState = rememberSwipeableState("A")
    val sizePx = with(LocalDensity.current) { (width - squareSize).toPx() }
    val anchors = mapOf(0f to "A", sizePx / 2 to "B", sizePx to "C")

    Box(
        modifier =
            Modifier.width(width)
                .swipeable(
                    state = swipeableState,
                    anchors = anchors,
                    thresholds = { _, _ -> FractionalThreshold(0.5f) },
                    orientation = Orientation.Horizontal
                )
                .background(Color.Black)
    ) {
        Box(
            Modifier.offset { IntOffset(swipeableState.offset.value.roundToInt(), 0) }
                .size(squareSize)
                .background(Color.Red),
            contentAlignment = Alignment.Center
        ) {
            Text(swipeableState.currentValue, color = Color.White, fontSize = 24.sp)
        }
    }
}