[General] Add failOffsetY prop to ReanimatedSwipeable

[willheisenberg]

Description

Adds an optional failOffsetY prop to ReanimatedSwipeable and forwards it to the internal pan gesture.

So far the swipe pan was configured only with activeOffsetX. Inside a vertical list with RefreshControl on Android, a slightly diagonal pull could start the native pull-to-refresh and then activate the swipe, which cancels the native touches. SwipeRefreshLayout doesn't retract on ACTION_CANCEL, so the indicator stays half-pulled. With failOffsetY (e.g. [-8, 8]) the swipe fails once the finger moves vertically first, and horizontal swiping keeps working.

The prop is only added to the pan config when set, so behavior without it is unchanged. Docs for ReanimatedSwipeable are updated.

Fixes #4563

Test plan

• yarn ts-check, yarn lint:js and yarn test in packages/react-native-gesture-handler pass.
• Verified the same change on an Android device (RN 0.87, Gesture Handler 3.3.0) in an app with the setup described in ReanimatedSwipeable: allow passing failOffsetY to the internal pan gesture #4563: without failOffsetY light diagonal pulls on a row leave the refresh indicator stuck; with failOffsetY={[-8, 8]} 10 out of 10 such pulls behaved correctly, and swiping rows horizontally still works.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 088fb9f8-7325-49c0-a87a-d4409a2d6a91

📥 Commits

Reviewing files that changed from the base of the PR and between ec9965a and 80ca7e6.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 30e746d2-317a-4ddf-aa3a-32aebe9f568f

📥 Commits

Reviewing files that changed from the base of the PR and between 23eb04a and 6adb005.

📒 Files selected for processing (1)

• packages/react-native-gesture-handler/src/__tests__/reanimatedSwipeableCallbacks.test.tsx

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Summary

Summary by CodeRabbit

• New Features
  • Added the optional failOffsetY setting to Reanimated Swipeable. Set a vertical movement threshold or range to make the swipe gesture fail before activation.
  • The setting accepts a number or a two-value range; in supported configurations, values can also be shared values. It remains unset by default, preserving existing behavior when not configured.
• Documentation
  • Updated the Reanimated Swipeable documentation with the setting’s accepted values, behavior, and default.

Walkthrough

ReanimatedSwipeable now accepts an optional failOffsetY prop and passes it to its internal pan gesture when defined. The documentation describes its accepted values and default. Tests check that configured offsets are forwarded and that omitted offsets remain unset.

Changes

ReanimatedSwipeable gesture configuration

Layer / File(s)	Summary
Define and forward failOffsetY packages/react-native-gesture-handler/src/components/ReanimatedSwipeable/ReanimatedSwipeableProps.ts, packages/react-native-gesture-handler/src/components/ReanimatedSwipeable/ReanimatedSwipeable.tsx, packages/docs-gesture-handler/docs/components/reanimated_swipeable.mdx, packages/react-native-gesture-handler/src/__tests__/reanimatedSwipeableCallbacks.test.tsx	SwipeableProps adds the optional numeric or two-number range prop. ReanimatedSwipeable passes the value to its pan gesture when defined and updates the configuration memo dependencies. The documentation describes the option and its effect. Tests check forwarding and confirm that the pan configuration has no offset properties when the prop is omitted.

Priority: ➖ Normal

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 6adb0

This adds an optional vertical failure offset to ReanimatedSwipeable, and behavior is unchanged when the prop is omitted. No merge-blocking risk was identified.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 6adb0

The change is small and opt-in. It uses the existing gesture pipeline without introducing new privileges or data access, and preserves configuration when the option is omitted. Platform-specific touch ownership after gesture failure remains incompletely verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The directly affected scope is gesture recognition and touch arbitration around component instances configured with failOffsetY. The production path does not establish expansion into tenant, service, environment, or data-store authority.

Trust Boundaries and Controls

• observed — The prop remains within the existing gesture-processing path. Touch action, simultaneous-gesture relationships, failure dependencies, blocking relationships, and lifecycle callbacks are unchanged by the production diff.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding the failOffsetY prop to ReanimatedSwipeable.
Linked Issues check	✅ Passed	Issue [#4563] requires an optional failOffsetY prop on ReanimatedSwipeable, unchanged forwarding to the internal pan gesture, and unchanged behavior when the prop is omitted. `ReanimatedSwipeableP…
Out of Scope Changes check	✅ Passed	The whole pull request changes the ReanimatedSwipeable prop type, internal pan configuration, related documentation, and focused tests. These changes support issue [#4563]. No unrelated change appea…

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Copilot review overview

🟡 Changes recommended

The new gesture-configuration path lacks regression coverage.

Review effort: Balanced
Findings: 1

Open (1)

• Add regression test for ReanimatedSwipeable failOffsetY forwarding · New

What changed in this PR

Adds configurable vertical failure thresholds to ReanimatedSwipeable, preventing vertical list gestures from being intercepted.

Changes:

• Exposes and forwards failOffsetY.
• Documents supported values and pull-to-refresh usage.

File	Description
ReanimatedSwipeableProps.ts	Defines the new prop.
ReanimatedSwipeable.tsx	Applies it to the pan gesture.
reanimated_swipeable.mdx	Documents the API.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.