Suggest an edit

Improve this article

Refine the answer for “What does requestIdleCallback() do?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

## Definition

```javascript
requestIdleCallback(callback, [options])
```

This function **registers a callback** that will be called **when the browser is not busy** painting or handling events, that is, *during idle time*.

---

## What this means

The browser paints frames roughly 60 times a second (every ~16.6 ms). If a given frame only took, say, 10 ms, the browser has **~6 ms of free time** left, and that is exactly where your `requestIdleCallback` can run.

So you can perform **minor or background tasks** that are not time-critical **without slowing down the interface**.

---

## Example

```javascript
requestIdleCallback((deadline) => {
  while (deadline.timeRemaining() > 0) {
    console.log('Running a background task');
  }
  console.log('The browser is busy again, waiting for the next idle period');
});
```

Here:

- `deadline` is a special object passed to the callback,
- `deadline.timeRemaining()` shows how many milliseconds are "free" before the next frame,
- you can do work **while there is time**, and if you did not finish, the browser will call the callback again in the next "idle window".

---

## How it works step by step

1. You call `requestIdleCallback(fn)`
2. The browser adds `fn` to the **"idle callbacks" task queue**
3. Once the Event Loop, painting, and microtasks are done, and there is time left before the next frame, the browser calls your callback
4. If the tab is inactive or there is no time, the callback can be delayed

---

## Function arguments

```javascript
requestIdleCallback(callback, { timeout: 2000 })
```

- `callback(deadline)` is a function that receives an object:
  - `deadline.timeRemaining()`, how many milliseconds are left "before busy";
  - `deadline.didTimeout`, `true` if the timeout has passed and the callback was called "forcibly".
- `options.timeout` is the maximum wait time (if there is no idle moment, the callback still runs after the given time).

---

## Example with splitting heavy work

```javascript
const tasks = Array.from({ length: 10000 }, (_, i) => i);

function processTasks(deadline) {
  while (deadline.timeRemaining() > 0 && tasks.length > 0) {
    const task = tasks.shift();
    // do part of the work
    console.log('Processed task', task);
  }

if (tasks.length > 0) {
    requestIdleCallback(processTasks);
  }
}

requestIdleCallback(processTasks);
```

This approach lets you **process thousands of items** without lag: the UI stays responsive because the work runs **in the pauses between frames**.

---

## Difference from setTimeout and requestAnimationFrame

| Criterion | `setTimeout` | `requestAnimationFrame` | `requestIdleCallback` |
|---|---|---|---|
| Purpose | Run after N ms | Run **before** a frame repaint | Run **in a pause between frames** |
| Priority | Medium | High (for animations) | Low (background tasks) |
| Depends on load | No | Yes, synced to the frame | Yes, called only if the browser is free |
| On an inactive tab | Can be throttled | Paused | Can be delayed for a long time |
| Use case | Timers, delays | Animations, smooth updates | Light background computation, caching, load logic |

---

## Important to know

- `requestIdleCallback` **is not available in every browser** (for example, not in Safari). It is better to have a **fallback**:

```javascript
  const ric = window.requestIdleCallback || function (cb) {
    return setTimeout(() => cb({ timeRemaining: () => 0, didTimeout: true }), 1);
  };
  ```
- It **should not be used for critical tasks**, because it may not be called for a long time (if the tab is under heavy load).

---

## Summary

| Property | Value |
|---|---|
| **What it does** | Calls a callback when the browser has free time |
| **Passes an object** | `deadline` with `timeRemaining()` and `didTimeout` |
| **When it runs** | In "idle windows" between frames |
| **Used for** | Background tasks, caching, loading data |
| **Cancelled via** | `cancelIdleCallback(id)` |
| **Returns** | A numeric ID, like timers |

Markdown · drag & drop images · ⌘B / ⌘I shortcuts632 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.