Running worklet functions on the UI runtime

The Worklets library provides three functions for running a worklet function on the UI Runtime from the RN Runtime: scheduleOnUI, runOnUIAsync and runOnUISync. They differ in whether the worklet function runs asynchronously or synchronously, and in what they return to the caller. Use the table below to pick the one that fits your case.

Comparison

	scheduleOnUI	runOnUIAsync	runOnUISync
Execution	Asynchronous	Asynchronous	Synchronous, blocks the caller until the worklet function returns
Returns	Nothing	A Promise that resolves with the worklet function's return value	The worklet function's return value directly
Web support	✅	✅	❌
Use when	You want to run a worklet function on the UI Runtime and don't need its result back	You need the worklet function's result back, but don't want to block the calling thread	You need the worklet function's result immediately, within the same synchronous flow

The values returned by runOnUIAsync and runOnUISync have to be serializable.

All three functions can be called from the RN Runtime, and additionally from the UI and Worker Runtimes when Bundle Mode is enabled. See Call tables for the full matrix.

Watch the execution

Schedule work without waiting

The UI thread runs the callback while the JS thread continues with the next line.

Code

Code

Colours connect each executing thread to its current code line. Recently executed lines fade over the next three ticks.

1function myFunction() {

2 'worklet';

3 console.log('Hello from the UI Runtime!');

4}

5

6scheduleOnUI(myFunction);

7console.log('The RN Runtime continues');

Await a result

The callback runs on the UI thread. Awaiting its Promise suspends this function; the JS thread remains available for other queued work.

Code

Code

Colours connect each executing thread to its current code line. Recently executed lines fade over the next three ticks.

1function compute() {

2 'worklet';

3 return 1;

4}

5

6const pending = runOnUIAsync(compute);

7console.log('The RN Runtime continues while the result is pending');

8const result = await pending;

9console.log(result); // 1

Read a result synchronously

The calling JS thread acquires the UI Runtime and executes the callback itself. It resumes the next line only after the result is ready.

Code

Code

Colours connect each executing thread to its current code line. Recently executed lines fade over the next three ticks.

1function myFunction(num) {

2 'worklet';

3 return num + 1;

4}

5

6const result = runOnUISync(myFunction, 0);

7console.log(result); // 1