Worklet Scheduling

Overview

Guidelines for scheduling functions between JavaScript and UI threads using React Native Worklets. This skill covers when and how to use scheduleOnRN and scheduleOnUI , proper function definition patterns, and avoiding unnecessary worklet directives.

When to Apply

Reference these guidelines when:

• Scheduling functions to run on UI thread from JS thread

• Calling JS thread functions from UI thread worklets

• Working with useAnimatedReaction or gesture handlers

• Batching shared value updates

• Implementing cross-thread communication in animations

Key Guidelines

Don't Use 'worklet' Directive Unless Explicitly Asked

Never use the "worklet" directive unless explicitly requested. In 99.9% of cases, there is no need to use it. scheduleOnUI handles worklet conversion automatically, so the directive is unnecessary. This also applies to gesture detector callbacks - you don't need to add the "worklet" directive in gesture handler callbacks.

Use scheduleOnRN and scheduleOnUI Instead of runOnJS and runOnUI

Use scheduleOnRN and scheduleOnUI from react-native-worklets instead of runOnJS and runOnUI from react-native-reanimated .

Don't do this:

import { runOnJS, runOnUI } from "react-native-reanimated";

Instead, do this:

import { scheduleOnRN, scheduleOnUI } from "react-native-worklets";

Type Definitions

function scheduleOnRN<Args extends unknown[], ReturnValue>( fun: | ((...args: Args) => ReturnValue) | RemoteFunction<Args, ReturnValue> | WorkletFunction<Args, ReturnValue>, ...args: Args ): void;

function scheduleOnUI<Args extends unknown[], ReturnValue>( fun: (...args: Args) => ReturnValue, ...args: Args ): void;

Usage Patterns

Always Define Functions Outside Using useCallback

Both scheduleOnRN and scheduleOnUI follow the same usage pattern: always define the function outside using useCallback and pass the function reference (not inline arrow functions).

When to use:

• scheduleOnRN : Call JavaScript thread functions from UI thread worklets (like in useAnimatedReaction , gesture handlers, or useAnimatedStyle )

• scheduleOnUI : Schedule functions to run on the UI thread

Don't do this – inline arrow function:

// ❌ scheduleOnRN with inline function useAnimatedReaction( () => currentIndex.get(), (nextIndex) => { scheduleOnRN(() => { setState(newValue); }); } );

// ❌ scheduleOnUI with inline function scheduleOnUI(() => { scale.set(withSpring(1.2)); });

Instead, do this – define function outside:

// ✅ scheduleOnRN - JS thread function const updateState = useCallback(() => { setState(newValue); }, [dependencies]);

useAnimatedReaction( () => currentIndex.get(), (nextIndex) => { scheduleOnRN(updateState); // pass function reference } );

// ✅ scheduleOnUI - UI thread function const updateAnimations = useCallback(() => { scale.set(withSpring(1.2)); opacity.set(withSpring(0.8)); }, []);

scheduleOnUI(updateAnimations); // pass function reference

Passing Arguments

Arguments are passed directly (not as an array) using rest parameter syntax:

// Single argument const updateState = useCallback((newValue: number) => { setState(newValue); }, []);

scheduleOnRN(updateState, newValue); // ✅ correct

// Multiple arguments const handleUpdate = useCallback((index: number, value: string) => { setState({ index, value }); }, []);

scheduleOnRN(handleUpdate, index, value); // ✅ correct - pass directly, not as array scheduleOnUI(handleUpdate, index, value); // ✅ same pattern for scheduleOnUI

Common Use Cases

scheduleOnRN Use Cases

• React state setters (setState , setExtendedSlides , etc.)

• API calls or side effects

• Video player controls (pause , resume , seek )

• Haptic feedback

• Navigation functions

Example:

// scheduleOnRN example const pause = useCallback(() => { videoPlayerRef.current?.pause(); }, []);

useAnimatedReaction( () => isDragging.get(), (current) => { if (current) { scheduleOnRN(pause); } } );

scheduleOnUI Use Cases

• Batch multiple shared value updates in the same frame

• UI thread worklet operations

Example:

// scheduleOnUI example - batch updates const batchUpdates = useCallback(() => { scale.set(withSpring(1.2)); opacity.set(withSpring(0.8)); }, []);

scheduleOnUI(batchUpdates);

Benefits

• Automatic Worklet Conversion: scheduleOnUI handles worklet conversion automatically

• Better Performance: Batching updates reduces UI thread overhead

• Type Safety: Better TypeScript support with proper type definitions

• Cleaner Code: No need for "worklet" directive in most cases

• Consistent API: Unified approach for cross-thread communication