> ## Documentation Index
> Fetch the complete documentation index at: https://docs.napps.io/llms.txt
> Use this file to discover all available pages before exploring further.

# React gestures

Use `gestureDetector` for native gesture recognition. It supports `tap`, `pan`, and `longPress`.
`drag` is available as a pan alias when that better describes the interaction.

## Tap

```tsx theme={null}
<gestureDetector
  gesture="tap"
  onEnd={(event) => {
    console.log("tap", event.x, event.y);
  }}
>
  <box style={{ width: 120, height: 48, backgroundColor: "#2563eb" }} />
</gestureDetector>
```

## Pan with a shared value

```tsx theme={null}
const offsetX = sv(0);

return (
  <gestureDetector
    gesture={{ type: "pan", minDistance: 8 }}
    onUpdate={mapEvent({ translationX: offsetX })}
    onEnd={(event) => {
      offsetX.value = spring(0, { velocity: event.velocityX });
    }}
  >
    <box style={animatedProps({ translationX: offsetX })} />
  </gestureDetector>
);
```

Use `mapEvent` when the callback only copies event fields into shared values. Use `event` or a normal callback when custom logic is needed.

## Long press

```tsx theme={null}
<gestureDetector
  gesture="longPress"
  onStart={() => setMenuOpen(true)}
  onFinalize={() => setMenuOpen(false)}
>
  <text>Hold for options</text>
</gestureDetector>
```

## Gesture event data

Gesture events can include `state`, `x`, `y`, `absoluteX`, `absoluteY`, `translationX`, `translationY`, `velocityX`, `velocityY`, `pointerCount`, and `timestamp`.

Lifecycle callbacks are `onBegin`, `onStart`, `onUpdate`, `onEnd`, `onCancel`, and `onFinalize`. `onUpdate` is continuous; use it sparingly and prefer `mapEvent` for direct animation updates.

## Best practices

* Keep gesture callbacks small and move visual updates into shared values.
* Use `minDistance` to prevent accidental pans from taps.
* Reset or settle shared values in `onEnd`, `onCancel`, or `onFinalize`.
* Do not perform network requests directly on every `onUpdate` event.
* Test gestures on a real device because native touch arbitration affects final behavior.