🧵
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 destructing, so you don't need to remember the exact order
const { postTask, ref } = useScheduler(options);

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

⚠️ react-use-scheduler use 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 useInView hook, ex:

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

Name	Type	Default
priority	string	TASK_PRIORITIES.userBlocking

One of:

• TASK_PRIORITIES.background for the lowest priority tasks.
• TASK_PRIORITIES.userVisible for medium priority tasks. This is the default if no priority is set.
• 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	TASK_PRIORITIES.userBlocking	Override the priority set in the options argument to the useInView 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 an error will be throw if the task is aborted before completion

ref

<Component ref={ref} />

You can pass the ref to a component to bind the tasks scheduled with postTask to the component lifecycle and visibility.

• If the component exits the viewport, all the incomming 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.