Motivation

Let's say you want to render something complex on a canvas in a React application. Canvas API is imperative, so to interact with it, you need to use the useEffect() hook. Unfortunately, if rendering takes too long, you can block the main thread and make your application unresponsive (especially on low-end devices).

The useTransitionEffect() hook provides a way to split long-running effects into smaller chunks to unblock the main thread. It uses scheduler package (from React) to schedule smaller units of work and coordinate it with React rendering.

Installation

This package requires React 17+ and scheduler 0.20+

# with npm
npm install use-transition-effect

# with yarn
yarn add use-transition-effect

Usage

const [isPending, startTransitionEffect, stopTransitionEffect] =
  useTransitionEffect();

The API is very similar to the useTransition hook from React. It returns a stateful value for the pending state of the transition effect, a function to start it, and a function to stop it.

startTransitionEffect lets you schedule a long-running effect without blocking the main thread. It expects a generator function as an argument, so you can yield to unblock the main thread:

startTransitionEffect(function* () {
  for (let item of items) {
    doSomeComplexSideEffects(item);
    yield;
  }
});

Additionally, you can yield and return a cleanup function that will run on transition stop (including unmount):

startTransitionEffect(function* () {
  const cleanup = () => cleanupSideEffects();

  for (let item of items) {
    doSomeComplexSideEffects(item);
    yield cleanup;
  }
  return cleanup;
});

stopTransitionEffect lets you stop the current long-running effect. You can use it as a useEffect cleanup:

useEffect(() => {
  startTransitionEffect(function* () {
    // effect
  });

  return () => stopTransitionEffect();
}, []);

isPending indicates when a transition effect is active to show a pending state:

function App() {
  const [isPending, startTransitionEffect, stopTransitionEffect] =
    useTransitionEffect();

  function handleStartClick() {
    startTransitionEffect(function* () {
      // do stuff, for example render something on a canvas
    });
  }
  function handleStopClick() {
    stopTransitionEffect();
  }

  return (
    <div>
      {isPending && <Spinner />}
      <button onClick={handleStartClick} disabled={isPending}>
        Start
      </button>
      <button onClick={handleStopClick} disabled={!isPending}>
        Stop
      </button>
    </div>
  );
}

The scheduler package exports the unstable_shouldYield() function that returns true if the current task takes too long. You can use it to decide when to yield:

import { unstable_shouldYield as shouldYield } from "scheduler";

startTransitionEffect(function* () {
  for (let item of items) {
    doSomeComplexSideEffects(item);
    if (shouldYield()) {
      yield;
    }
  }
});

If you want to update the state during a transition effect, you have to wrap this update with the unstable_runWithPriority() function from the scheduler package (with a priority higher than IdlePriority). Otherwise, the state update inside the transition effect will run when the effect ends:

import {
  unstable_runWithPriority as runWithPriority,
  unstable_NormalPriority as NormalPriority,
} from "scheduler";

startTransitionEffect(function* () {
  for (let item of items) {
    runWithPriority(NormalPriority, () => {
      setCount((prevCount) => prevCount + 1);
    });
    yield;
  }
});

License

MIT