Suggest an edit

Improve this article

Refine the answer for “What does useDeferredValue() 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)

## What `useDeferredValue()` does

`useDeferredValue()` defers the update of some value,
allowing React to **first render urgent updates**,
and only then the "unhurried" ones.

> Put simply:
> `useDeferredValue()` tells React:
> **"Don't rush to update this value, do it when you have free time."**

---

## Syntax

```javascript
const deferredValue = useDeferredValue(value);
```

- `value` is a regular state value or variable;
- `deferredValue` is the "deferred" version of that value,
which updates a bit later, once React finishes the urgent renders.

---

## Example: searching a large list

### Without `useDeferredValue`

```javascript
function Search({ data }) {
  const [query, setQuery] = useState("");

const filtered = data.filter((item) => item.includes(query)); // heavy

return (
    <>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      <List items={filtered} />
    </>
  );
}
```

The problem:

- Every character typed triggers filtering the whole collection.
- The UI lags, there's a "lag" while typing.

---

### With `useDeferredValue`

```javascript
import { useDeferredValue } from "react";

function Search({ data }) {
  const [query, setQuery] = useState("");
  const deferredQuery = useDeferredValue(query); // defer the processing

const filtered = data.filter((item) => item.includes(deferredQuery));

return (
    <>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      <List items={filtered} />
    </>
  );
}
```

What happens:

1. `query` updates **immediately** - the input field is responsive.
2. `deferredQuery` updates **a bit later** - React waits until the thread is free.
3. While filtering runs, you can even show a loading indicator.

---

## Difference between `useTransition` and `useDeferredValue`

| Feature | `useTransition` | `useDeferredValue` |
|---|---|---|
| What it does | Wraps a **state update** | A deferred version of a **value** |
| Used where | Where you call `setState` | Where you use the value |
| Returns | `[isPending, startTransition]` | `deferredValue` |
| Control | You decide yourself what to "defer" | React itself defers the update |
| Complexity | Need to wrap the logic | Very simple - 1 line |

Essentially:

- `useTransition` -> defers the **action (setState)**.
- `useDeferredValue` -> defers the **result (value)**.

---

## Example: filtering with a loading indicator

```javascript
import { useDeferredValue } from "react";

function FilteredList({ items }) {
  const [query, setQuery] = useState("");
  const deferredQuery = useDeferredValue(query);

const filtered = items.filter((item) =>
    item.toLowerCase().includes(deferredQuery.toLowerCase())
  );

const isStale = query !== deferredQuery; // the update hasn't caught up yet

return (
    <>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      {isStale && <p>Filtering...</p>}
      <List items={filtered} />
    </>
  );
}
```

Behavior:

- While typing, the field reacts instantly.
- Rendering the large list is slightly deferred.
- "Filtering..." is shown while `deferredQuery` hasn't updated yet.

---

## When to use `useDeferredValue()`

| When | Why |
|---|---|
| Heavy filtering or sorting based on typed input | So typing doesn't lag |
| Rendering a large list or table | So rendering doesn't block the UI |
| The component receives an expensive prop value | So React doesn't recompute it instantly |
| You want a smooth update without the extra code of `useTransition` | It's a "shortcut" to the same goal |

---

## When you **don't need** to use it

| Case | Why |
|---|---|
| Updates are light | React handles it fine anyway |
| There are no delays while typing | Excessive |
| An instant display is required | `useDeferredValue` is specifically *not instant* |
| For asynchronous requests | `useEffect` / `React Query` is better |

---

## Under the hood

`useDeferredValue` uses the same mechanism as `startTransition`:
React marks the update as **"not urgent" (low-priority)**.
The difference is that:

- you **don't control** it explicitly,
- React **decides itself** when to catch the value up.

---

## Summary

| Question | Answer |
|---|---|
| What does `useDeferredValue()` do | Returns a deferred version of a value that updates with low priority |
| Why it's needed | To keep the interface responsive during heavy renders |
| When to use it | When rendering or computation depends on frequently updated state |
| When not to use it | If updates are light or must be instant |
| Analogy | Like `useTransition`, just "in one line" |

---

**Main idea:**

> `useDeferredValue(value)` -> "Don't update this value right away.
> Wait until the user stops actively interacting."

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

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.