oneHandedGesture
public fun Modifier.oneHandedGesture(
gestureConfiguration: OneHandedGestureConfiguration,
onGestureLabel: String?,
@IntRange(from = 0L) showIndicatorDelayMillis: Long,
enabledInAmbient: Boolean = false,
interactionSource: MutableInteractionSource? = null,
onGestureAvailable: () -> Unit = {},
onGesture: suspend () -> Unit,
): ModifierRegisters a gesture handler.
Note: Gesture recognition can be explicitly disabled across a component hierarchy by providing false` to LocalOneHandedGestureEnabled.
Visibility Management: This gesture handler is active as long as the Modifier is part of the composition. On its own, it does not track whether the composable is visible or clipped (e.g., in a Lazy layout).
To prevent accidental triggers from off-screen items, developers should apply this modifier conditionally. For many cases, androidx.compose.ui.layout.onVisibilityChanged Modifier can be used to determine the visibility of a composable.
Example usage in a list:
var isVisible { mutableStateOf(false) }
val gestureModifier = remember(isVisible) {
if (isVisible) Modifier.oneHandedGesture() else Modifier
}
Box(
modifier = Modifier
.onVisibilityChanged { isVisible = it }
.then(gestureModifier)
) {
...
}Haptics: When a gesture is successfully triggered, the system automatically performs haptic feedback to acknowledge the interaction; developers do not need to trigger haptics manually within onGesture.
Example of adding one-handed gesture handler to a androidx.wear.compose.material3.Button:
Example of adding one-handed gesture handler that is enabled in ambient mode to a androidx.wear.compose.material3.Button:
Example of adding one-handed gesture handler to a androidx.wear.compose.foundation.lazy.TransformingLazyColumn:
Example of adding one-handed gesture handler to a androidx.wear.compose.foundation.pager.HorizontalPager:
Example of adding one-handed gesture handler to a androidx.wear.compose.foundation.pager.VerticalPager:
See also the UI Design Guides for One-Handed Gestures
Parameters
| gestureConfiguration | The OneHandedGestureConfiguration containing the configuration for this gesture. |
| onGestureLabel | Semantic label used by accessibility services to describe the purpose of this gesture. This is highly recommended for ensuring that users with screen readers understand what action will be performed. |
| showIndicatorDelayMillis | The delay, in milliseconds, before the gesture indicator is shown - i.e. between the gesture becoming the highest-priority gesture for its action and onGestureAvailable being invoked. Must be non-negative. |
| enabledInAmbient | Whether the gesture should remain active in ambient mode. |
| interactionSource | MutableInteractionSource that will be used to dispatch androidx.compose.foundation.interaction.PressInteraction.Press and an immediate androidx.compose.foundation.interaction.PressInteraction.Release when this gesture is triggered. This allows UI components to visually react (such as triggering a touch ripple or pressed state animation) upon gesture activation. |
| onGestureAvailable | A callback invoked by the system to signal that this gesture is currently available as a high-priority action. Developers should use this callback to call showIndicator on the indicator state to trigger the associated visual feedback. |
| onGesture | The callback invoked when the gesture is triggered. |
oneHandedGesture
public fun Modifier.oneHandedGesture(
gestureConfiguration: OneHandedGestureConfiguration,
onGestureLabel: String?,
enabledInAmbient: Boolean = false,
interactionSource: MutableInteractionSource? = null,
onGestureAvailable: () -> Unit = {},
onGesture: suspend () -> Unit,
): ModifierRegisters a gesture handler.
Note: Gesture recognition can be explicitly disabled across a component hierarchy by providing false` to LocalOneHandedGestureEnabled.
Visibility Management: This gesture handler is active as long as the Modifier is part of the composition. On its own, it does not track whether the composable is visible or clipped (e.g., in a Lazy layout).
To prevent accidental triggers from off-screen items, developers should apply this modifier conditionally. For many cases, androidx.compose.ui.layout.onVisibilityChanged Modifier can be used to determine the visibility of a composable.
Example usage in a list:
var isVisible { mutableStateOf(false) }
val gestureModifier = remember(isVisible) {
if (isVisible) Modifier.oneHandedGesture() else Modifier
}
Box(
modifier = Modifier
.onVisibilityChanged { isVisible = it }
.then(gestureModifier)
) {
...
}Haptics: When a gesture is successfully triggered, the system automatically performs haptic feedback to acknowledge the interaction; developers do not need to trigger haptics manually within onGesture.
Example of adding one-handed gesture handler to a androidx.wear.compose.material3.Button:
Example of adding one-handed gesture handler that is enabled in ambient mode to a androidx.wear.compose.material3.Button:
Example of adding one-handed gesture handler to a androidx.wear.compose.foundation.lazy.TransformingLazyColumn:
Example of adding one-handed gesture handler to a androidx.wear.compose.foundation.pager.HorizontalPager:
Example of adding one-handed gesture handler to a androidx.wear.compose.foundation.pager.VerticalPager:
See also the UI Design Guides for One-Handed Gestures
Parameters
| gestureConfiguration | The OneHandedGestureConfiguration containing the configuration for this gesture. |
| enabledInAmbient | Whether the gesture should remain active in ambient mode. |
| interactionSource | MutableInteractionSource that will be used to dispatch androidx.compose.foundation.interaction.PressInteraction.Press and an immediate androidx.compose.foundation.interaction.PressInteraction.Release when this gesture is triggered. This allows UI components to visually react (such as triggering a touch ripple or pressed state animation) upon gesture activation. |
| onGestureLabel | Semantic label used by accessibility services to describe the purpose of this gesture. This is highly recommended for ensuring that users with screen readers understand what action will be performed. |
| onGestureAvailable | A callback invoked by the system to signal that this gesture is currently available as a high-priority action. Developers should use this callback to call showIndicator on the indicator state to trigger the associated visual feedback. It is invoked after a delay of OneHandedGestureDefaults.ShowIndicatorDelayMillis, use the overload with showIndicatorDelayMillis parameter to customize this delay. |
| onGesture | The callback invoked when the gesture is triggered. |
