use-transition-effect

use-transition-effect

Run long effects without blocking the main thread

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. The generator function receives the shouldYield function, which returns true if the current task takes too long:

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

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

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

  for (let item of items) {
    doSomeComplexSideEffects(item);
    if (shouldYield()) {
      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>
  );
}

License

MIT