Worklets وتشغيل التعليمات البرمجية على خيط واجهة المستخدم

A worklet is a JavaScript function that Reanimated runs on the UI thread instead of the JavaScript thread. Reanimated's Babel plugin detects functions marked with the 'worklet' directive string at the top of their body and transforms them at build time into a form that can be sent to and executed on the UI thread.

Worklets are the core mechanism that allows Reanimated to process gesture data and update animations frame-by-frame at 60fps without ever involving the JavaScript thread or the bridge. They are the key architectural innovation that separates Reanimated from the classic Animated API.

The 'worklet' string literal at the top of a function body is a special directive — similar to 'use strict'. The Reanimated Babel plugin scans for it and transforms the function so it can be serialized and run on the UI thread. Without this directive, calling the function from a worklet context would silently execute on the JS thread, causing potential crashes or incorrect behavior.

Functions passed to Reanimated hooks like useAnimatedStyle are automatically treated as worklets even without the directive. Regular utility functions called FROM those hooks need the directive explicitly.

Touch events on mobile are processed on the UI thread. When a user drags a finger, the device generates touch events many times per second (up to 120fps on modern devices). If gesture handling required the JavaScript thread, every touch event would cross the bridge — introducing latency that makes interactions feel laggy and unresponsive.

With worklets, the gesture handler and the animation response both run on the UI thread. The animated value updates happen in the same thread tick as the touch event, achieving true zero-latency gesture response that feels like native iOS/Android interactions.

Reanimated provides hooks like useAnimatedScrollHandler and useAnimatedGestureHandler whose callbacks run as worklets on the UI thread. Inside these callbacks you can call any function marked with 'worklet' directly, and you can read and write shared values using .value.

Writing to a shared value inside a gesture callback is how you make an animated component track the user's finger in real time — the write happens on the UI thread and the animated style reacts immediately.

Worklets run on the UI thread and cannot directly call React functions, setState, or navigation methods. When you need to trigger JavaScript-thread code from a worklet (for example, updating React state or navigating after a gesture completes), use runOnJS.

runOnJS(fn)(args) schedules the function to run on the JS thread on the next available frame. This lets gesture handlers update React state or call navigation after an interaction without breaking the worklet execution model.

The reverse of runOnJS is runOnUI. This lets you schedule a worklet function to execute on the UI thread from the JavaScript thread. It is useful for triggering animations from JS-thread event handlers (like button presses) while keeping the animation logic itself in a worklet.

In most cases you simply assign to sharedValue.value (which already runs on the UI thread), so runOnUI is less commonly needed. It becomes necessary when you need to batch multiple UI-thread operations atomically.

Worklets are not full JavaScript — they run in a restricted environment that cannot access Node.js APIs, React hooks, component state, or the full JavaScript runtime. You cannot console.log from a worklet in production (it is a no-op). You cannot import third-party modules inside a worklet unless they explicitly support Reanimated.

Keep worklets focused on math and value computation: clamping, mapping ranges, computing physics, reading gesture data. Move everything else to the JS thread using runOnJS.

useAnimatedReaction lets you watch a shared value or derived expression and run a worklet (or call back to JS) when it changes. It takes two worklet functions: a prepare function that reads values, and a reaction function that receives the current and previous values.

This is useful for triggering side effects when an animation reaches a threshold — like calling navigation to dismiss a screen when an offset exceeds 50% of the screen height.

useDerivedValue creates a new shared value that is automatically computed from other shared values. The derivation function is a worklet that runs on the UI thread whenever any dependency changes. It is the Reanimated equivalent of useMemo, but for shared values.

Use derived values to compute complex transformations once (rather than repeating the math in each useAnimatedStyle) or to drive multiple style hooks from a single source of truth.

A scroll parallax header demonstrates worklets in practice. The scroll offset drives multiple derived values — a background image moves at half speed, a title fades out, and a sticky mini-header fades in. All these derivations run as worklets triggered by Animated.event scroll tracking.

The entire parallax effect runs at 60fps with zero JavaScript thread involvement because every step — scroll tracking, value derivation, and style computation — is a worklet on the UI thread.

Debugging worklets is harder than regular JavaScript because they run on a separate thread. Use console.log inside worklets during development (it works in debug mode via Hermes), and use useAnimatedReaction with runOnJS(console.log) for production-safe logging.

Reanimated also integrates with React DevTools Profiler to visualize which worklets are running. If animations behave unexpectedly, add a useDerivedValue to log the computed value at each frame to identify where the calculation diverges from expectations.

Test your understanding of React Native Mobile Development concepts from this lesson.

In this lesson you learned: worklets are functions marked with the 'worklet' directive that run on the UI thread bypassing the bridge, runOnJS schedules JS-thread calls from worklets for React state and navigation, and useDerivedValue and useAnimatedReaction let you derive and watch shared values in worklet context. Next up we build a draggable card using Pan gestures with React Native Gesture Handler.