Gesture detector - EXPRESSO Docs

gestureDetector adds native gesture recognition around a subtree. It is experimental and may change in a future runtime.

Properties

Property	Accepted value	Description
`enabled`	`boolean`	Enables gesture recognition.
`gesture`	`"pan" \| "tap" \| "longPress" \| "drag" \| GestureConfig`	Gesture kind or configured gesture.
`onBegin`	`(event: GestureEvent) => void`	Called when recognition begins.
`onStart`	`(event: GestureEvent) => void`	Called when the gesture activates.
`onUpdate`	`(event: GestureEvent) => void`	Called while the gesture changes.
`onEnd`	`(event: GestureEvent) => void`	Called when it ends normally.
`onCancel`	`(event: GestureEvent) => void`	Called when recognition is cancelled.
`onFinalize`	`(event: GestureEvent) => void`	Called after completion or cancellation.
`style`	`StyleProperties`	Layout and appearance values.
`children`	`ReactNode`	Subtree receiving gesture handling.
`key`	`string \| number`	React key for dynamic detectors.
`class`	`string`	Registered style name for this node only.

interface GestureConfig {
  type?: "pan" | "tap" | "longPress" | "drag";
  maxDistance?: number;
  minDistance?: number;
}

interface GestureEvent {
  state: "began" | "active" | "ended" | "cancelled";
  x: number;
  y: number;
  absoluteX: number;
  absoluteY: number;
  translationX: number;
  translationY: number;
  velocityX: number;
  velocityY: number;
  pointerCount: number;
  timestamp: number;
}

Tap

Use tap for a completed press with limited pointer movement. Restore temporary feedback from onFinalize, which also runs when the gesture is cancelled.

const scale = sv(1);

<gestureDetector
  gesture={{ type: "tap", maxDistance: 12 }}
  onBegin={() => {
    scale.value = timing(0.96, { duration: 80 });
  }}
  onFinalize={() => {
    scale.value = timing(1, { duration: 120 });
  }}
>
  <box
    style={animatedProps({
      scale,
      width: 160,
      height: 48,
      borderRadius: 12,
      backgroundColor: "#2563eb"
    })}
  >
    <text style={{ color: "#ffffff", textAlignment: "center" }}>Add to cart</text>
  </box>
</gestureDetector>

Pan

Use pan when movement should update the UI continuously. mapEvent copies gesture values into shared values without a React render on every pointer update.

const offsetX = sv(0);

<gestureDetector
  gesture={{ type: "pan", minDistance: 8 }}
  onUpdate={mapEvent({ translationX: offsetX })}
  onEnd={(event) => {
    offsetX.value = spring(0, { velocity: event.velocityX });
  }}
>
  <box
    style={animatedProps({
      translationX: offsetX,
      width: 180,
      height: 100,
      borderRadius: 16,
      backgroundColor: "#dbeafe"
    })}
  />
</gestureDetector>

Long press

Use longPress for hold actions. onStart runs after the native long-press threshold is reached.

const alpha = sv(0.7);

<gestureDetector
  gesture={{ type: "longPress", maxDistance: 16 }}
  onStart={() => {
    alpha.value = timing(1, { duration: 120 });
  }}
  onFinalize={() => {
    alpha.value = timing(0.7, { duration: 120 });
  }}
>
  <box
    style={animatedProps({
      alpha,
      width: 180,
      height: 56,
      borderRadius: 12,
      backgroundColor: "#f59e0b"
    })}
  >
    <text style={{ textAlignment: "center" }}>Hold for options</text>
  </box>
</gestureDetector>

Drag

drag is an alias for the native pan implementation. Use it when the UI represents a draggable object; its lifecycle and event data match pan.

const offsetY = sv(0);

<gestureDetector
  gesture={{ type: "drag", minDistance: 8 }}
  onUpdate={mapEvent({ translationY: offsetY })}
  onEnd={(event) => {
    offsetY.value = spring(0, { velocity: event.velocityY });
  }}
>
  <box
    style={animatedProps({
      translationY: offsetY,
      width: 180,
      height: 100,
      borderRadius: 16,
      backgroundColor: "#dbeafe"
    })}
  >
    <text style={{ textAlignment: "center" }}>Drag me</text>
  </box>
</gestureDetector>

Use mapEvent for high-frequency gesture updates and a callback when you need custom logic. See React gestures for cancellation and animation patterns.

​Properties

​Tap

​Pan

​Long press

​Drag

Properties

Tap

Pan

Long press

Drag