https://github.com/valcol/react-use-scheduler
A React hook that allows you to schedule tasks and automatically orchestrate them based on your component lifecycle and visibility.
https://github.com/valcol/react-use-scheduler
hook inp performance react scheduler scheduling task-management task-scheduler webperformance
Last synced: 17 days ago
JSON representation
A React hook that allows you to schedule tasks and automatically orchestrate them based on your component lifecycle and visibility.
- Host: GitHub
- URL: https://github.com/valcol/react-use-scheduler
- Owner: valcol
- License: mit
- Created: 2022-10-05T15:15:24.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-01-04T13:01:04.000Z (about 3 years ago)
- Last Synced: 2025-10-08T08:35:48.259Z (4 months ago)
- Topics: hook, inp, performance, react, scheduler, scheduling, task-management, task-scheduler, webperformance
- Language: JavaScript
- Homepage:
- Size: 147 KB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
🧵
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](https://developer.mozilla.org/en-US/docs/Web/API/Scheduler). 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
```js
// 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](https://developer.mozilla.org/en-US/docs/Web/API/Scheduler),
> make sure to install the [polyfill](https://github.com/GoogleChromeLabs/scheduler-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.
```js
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 (
{hasBeenClicked ? "Clicked!" : "Click Me!"}
);
};
```
# API
## Options
Provide these as the options argument to the `useInView` hook, ex:
```js
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`
```js
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`
```js
```
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.