Suggest an edit

Improve this article

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

The `startTransition()` function lets you mark a state update (`setState`)
as **unhurried** (a low-priority update).

This gives React the ability to:

- **pause** or **defer** a heavy render,
- **first** handle important updates (for example, typing, clicks),
- and then - handle the "secondary" ones (filtering, sorting, rendering lists, etc.).

---

## Syntax

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

startTransition(() => {
  // call setState here
});
```

or with the hook:

```javascript
const [isPending, startTransition] = useTransition();

startTransition(() => {
  // same thing
});
```

---

## Example

Imagine: the user is typing into a search field,
while you filter a large data array - 10,000 items.

### Without `startTransition` (the UI "freezes")

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

const handleChange = (e) => {
    const value = e.target.value;
    setQuery(value);
    setResults(filterBigArray(value)); // heavy operation
  };

return (
    <>
      <input value={query} onChange={handleChange} />
      <List data={results} />
    </>
  );
}
```

The problem:

- Every character in `input` triggers a *list render*.
- React is busy, so typing **lags**.

---

### With `startTransition`

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

function Search() {
  const [query, setQuery] = useState("");
  const [results, setResults] = useState([]);

const handleChange = (e) => {
    const value = e.target.value;
    setQuery(value); // urgent (high-priority)

startTransition(() => {
      setResults(filterBigArray(value)); // not urgent (low-priority)
    });
  };

return (
    <>
      <input value={query} onChange={handleChange} />
      <List data={results} />
    </>
  );
}
```

Now React:

- Immediately updates `query` first, so the input field does not lag.
- Then, when it has time, recalculates `results`.

The UI stays smooth and responsive.

---

## What happens under the hood

| Step | What React does |
|---|---|
| You call `startTransition(() => setState())` | React marks the update as "low-priority" |
| The user keeps interacting | Urgent updates (`setQuery`) run immediately |
| React finishes the urgent tasks | Then it starts the "heavy" computation |
| When it is ready - the UI updates | Without lags or freezes |

---

## Example with an indicator

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

function FilterList({ data }) {
  const [filter, setFilter] = useState("");
  const [filtered, setFiltered] = useState(data);
  const [isPending, startTransition] = useTransition();

const handleChange = (e) => {
    const value = e.target.value;
    setFilter(value);

startTransition(() => {
      const result = data.filter(item => item.includes(value));
      setFiltered(result);
    });
  };

return (
    <>
      <input value={filter} onChange={handleChange} />
      {isPending && <p>Filtering...</p>}
      <ul>
        {filtered.map((item, i) => <li key={i}>{item}</li>)}
      </ul>
    </>
  );
}
```

While filtering is in progress, `isPending = true`,
React shows "Filtering...",
and meanwhile **typing stays instant** - no lags.

---

## What you can do inside `startTransition`

You can:

- call `setState` (even several times);
- compute derived data (for example, filter, sort);
- run memoization, if it does not block the interface.

You cannot:

- use asynchronous `await`;
- set timers (`setTimeout`) - React must control everything itself.

---

## Important to remember

| Trait | Explanation |
|---|---|
| Only works in React 18+ | Because it requires Concurrent Rendering |
| Does not guarantee instant execution | React decides when to start it |
| Does not cancel other updates | It just lowers the priority |
| Works **only with React state** | It does not manage external async requests |
| Can be used **outside a component** | `startTransition` is available directly from `react` |

---

## Summary

| Question | Answer |
|---|---|
| What does `startTransition()` do | Marks a state update as "unhurried" so React can pause or defer it |
| When React runs it | After all urgent updates (typing, clicks, hover) |
| Why it is needed | So the interface does not "freeze" during heavy computations or renders |
| What it returns | Nothing (it is managed together with `isPending` from `useTransition`) |
| When to use it | For filtering, navigation, sorting, updates to large lists |
| When not to use it | For ordinary `setState` and asynchronous API requests |

---

**Main idea:**

> `startTransition()` is a way to tell React:
> "Let the interface stay responsive,
> and you can do this update a little later."
</content>

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

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.