🧵
react-use-scheduler

A React hook that allows you to schedule tasks and automatically orchestrate them based on your component lifecycle and visibility.

npm i react-use-scheduler

yarn add react-use-scheduler

react-use-scheduler helps you manage and prioritize tasks using the browser Scheduler API. This allows you to prioritize the tasks that are the most important for a good user experience, making your page more responsive, while still allowing less critical work to be done. If the component associated with the tasks is no longer visible on the screen, the priorities of current and incoming tasks will be automatically lowered. If the component becomes visible again, the task priorities will be restored. Additionally, any tasks that are scheduled will be cancelled if the component is unmounted.

How to use

// Use object destructuring, so you don't need to remember the exact order
const { postTask, ref } = useScheduler(options);

// Or array destructuring if you want to customize the field names
const [postTask, ref] = useScheduler(options);

⚠️ react-use-scheduler uses the Scheduler API, make sure to install the polyfill if needed.

The useScheduler hook returns a postTask function and a ref that you can pass to a component to bind the tasks scheduled with postTask to the component lifecycle and visibility. You can pass a default priority as an option if you want.

import React, { useState } from "react";
import useScheduler, { TASK_PRIORITIES } from "react-use-scheduler";
//...

const Component = () => {
  const { postTask, ref } = useScheduler();
  const [hasBeenClicked, setHasBeenClicked] = useState(false);

  const onClick = () => {
    setHasBeenClicked(true);
    postTask(someLongTask, {
      priority: TASK_PRIORITIES.userVisible,
    });
    postTask(() => sendTracking("click"), {
      priority: TASK_PRIORITIES.background,
      detached: true,
    });
  };

  return (
    <button onClick={onClick} ref={ref}>
      {hasBeenClicked ? "Clicked!" : "Click Me!"}
    </button>
  );
};

API

Options

Provide these as the options argument to the useScheduler hook, ex:

const { postTask, ref } = useScheduler({
  defaultPriority: TASK_PRIORITIES.userVisible,
});

Name	Type	Default
defaultPriority	string	TASK_PRIORITIES.userBlocking

One of:

• TASK_PRIORITIES.background for the lowest priority tasks.
• TASK_PRIORITIES.userVisible for medium priority tasks.
• TASK_PRIORITIES.userBlocking for critical tasks that need to run at high priority.

Return

postTask

postTask(fn, options);

Options

Name	Type	Default	Description
priority	string	defaultPriority	Override the defaultPriority set in the options argument to the useScheduler hook.
detached	boolean	false	If set to true, the task will not be affected by the component's lifecycle. The priority will stay the same and the task will not be cancelled if the component is unmounted.
throwOnAbort	boolean	false	If set to true, the returned promise rejects with an AbortError if the task is aborted before completion. Otherwise it resolves with undefined.

Any other option (e.g. delay) is passed to scheduler.postTask. A custom signal is only honored for detached tasks, as attached tasks use the component's own signal.

ref

<Component ref={ref} />

You can pass the ref to a DOM element, or to a component that forwards it to one (with forwardRef before React 19), to bind the tasks scheduled with postTask to the component lifecycle and visibility.

• If the component exits the viewport, all the incoming and current task priorities will be set to background.
• If the component re-enters the viewport, all task priorities will be restored to their initial values.
• If the component is unmounted, all tasks will be aborted, as will any attached task posted afterwards. See throwOnAbort for how aborted tasks settle.