(worklets); avoid React state updates every frame.
If a JS-side effect is required (navigation, analytics, state set), call it via
scheduleOnRN
.
Verify on-device (Hermes inspector), not “Remote JS Debugging”.
Core patterns
Shared values are the “wire format” between runtimes
Use
useSharedValue
for numbers/strings/objects that must be read/written from both UI and JS.
Derive styles with
useAnimatedStyle
.
Prefer
withTiming
for UI tweens;
withSpring
for physics.
UI thread vs JS thread: the only rule that matters
Gesture callbacks and animated styles should stay workletized (UI runtime).
Only bridge to JS when you must (via
scheduleOnRN
).
See:
references/worklets-and-threading.md
Gesture Handler: use one API style per subtree
Default to
hook API
(
usePanGesture
,
useTapGesture
, etc.).
Do
not
nest GestureDetectors that use different API styles (hook vs builder).
Do
not
reuse the same gesture instance across multiple detectors.
See:
references/gestures.md
CSS Transitions (Reanimated 4)
Use when a style value changes due to React state/props and you just want it to animate.
Rules of thumb:
Always set
transitionProperty
+
transitionDuration
.
Avoid
transitionProperty: 'all'
(perf + surprise animations).
Discrete properties (e.g.
flexDirection
) won’t transition smoothly; use Layout Animations instead.
See:
references/css-transitions-and-animations.md
Layout animations
Use when elements enter/exit, or when layout changes due to conditional rendering/reflow.
Prefer presets first (entering/exiting, keyframes, layout transitions). Only reach for fully custom layout animations when presets can’t express the motion.
See:
references/layout-animations.md
Scroll-linked animations
Prefer Reanimated scroll handlers/shared values; keep worklet bodies tiny. For full recipes, see:
references/recipes.md
Troubleshooting checklist
“Failed to create a worklet” / worklet not running
Ensure the correct Babel plugin is configured for your environment.
Expo: handled by
babel-preset-expo
when installed via
expo install
.
Bare RN: Reanimated 4 uses
react-native-worklets/plugin
.
Gesture callbacks not firing / weird conflicts
Ensure the app root is wrapped with
GestureHandlerRootView
.
Don’t reuse gestures across detectors; don’t mix hook and builder API in nested detectors.
Needing to call JS from a worklet
Use
scheduleOnRN(fn, ...args)
.
fn
must be defined in JS scope (component body or module scope), not created inside a worklet.
Jank / dropped frames
Check for large objects captured into worklets; capture primitives instead.
Avoid
transitionProperty: 'all'
.
Don’t set React state every frame.
See:
references/debugging-and-performance.md
Bundled references (open only when needed)
references/setup-and-compat.md
Expo vs bare setup, New Architecture requirement, common incompatibilities.
references/worklets-and-threading.md
UI runtime,
scheduleOnUI
/
scheduleOnRN
, closure capture, migration notes.
references/gestures.md
GestureDetector, hook API patterns, composition, gotchas.
references/css-transitions-and-animations.md
Reanimated 4 CSS transitions/animations quick reference.
references/layout-animations.md
entering/exiting/layout transitions and how to pick.