Suggest an edit

Improve this article

Refine the answer for “What does useInsertionEffect() do (React 18)?”. 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 useInsertionEffect() does

useInsertionEffect() is a **special hook** that runs **even earlier than** useLayoutEffect, during the "insertion" of elements into the DOM (insertion phase).

It lets you **insert CSS rules synchronously**, before the browser performs layout and paint.

> Put simply: useInsertionEffect is needed to **insert styles** (CSS, emotion, styled-components) **before the browser has a chance to "measure" the DOM and paint the page.**

---

## Syntax

```javascript
useInsertionEffect(() => {
  // insert or generate styles inside a <style> tag
}, [dependencies]);
```

Similar to useEffect and useLayoutEffect, but runs **even earlier**, literally **before any layout effect**.

---

## Order of effect execution in React 18

| Stage | What it does | When it's called |
|---|---|---|
| useInsertionEffect | inserts CSS or other synchronous dependencies that affect layout | before layout effects |
| useLayoutEffect | measures or modifies the DOM | after styles are inserted, but before paint |
| useEffect | side effects (asynchronous, not affecting the DOM) | after paint |

---

### Visual timeline:

```javascript
Render → DOM inserted → [useInsertionEffect] → [useLayoutEffect] → Paint → [useEffect]
```

---

## Example (simplified)

Imagine we have a dynamic styling library that inserts a `<style>` tag with the required rules on every render.

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

return () => document.head.removeChild(style);
  }, [color]);

return <div className="dynamic-box">Box</div>;
}
```

Here:

- React calls useInsertionEffect **before painting**.
- The style is inserted **before layout**, so the browser **never shows an "unstyled" or "flashing" element.**

---

## Why it's needed (and for whom)

useInsertionEffect() is needed mainly by **CSS-in-JS libraries** (for example, **emotion, styled-components v6, stitches**, etc.) to:

1. **Guarantee the order in which styles are inserted** (for example, so overrides work correctly);
2. **Avoid a "flash of styles"** during server-side rendering or hydration;
3. **Insert CSS synchronously** with DOM creation, without visual lag.

---

## Important

| Rule | Explanation |
|---|---|
| You cannot work with the DOM directly | At call time the DOM is not yet "ready" for measurements |
| You can only insert synchronous dependencies (CSS) | Everything else belongs in useLayoutEffect or useEffect |
| Use it only for style-insertion systems | React warns if it's used in ordinary components |
| Safe with SSR | React does not call it on the server (only on the client) |

---

## Comparison with other effects

| Hook | When it runs | What for |
|---|---|---|
| useInsertionEffect | Before layout | Inserting CSS, styling library work |
| useLayoutEffect | After the DOM changes, before paint | Measuring the DOM, positioning, synchronization |
| useEffect | After paint | API requests, subscriptions, side effects |

---

## Summary

| Question | Answer |
|---|---|
| What useInsertionEffect() does | Lets you insert styles (CSS) synchronously before layout, to avoid visual artifacts |
| When it's called | After the DOM updates, but before layout effects and before painting |
| When to use it | Only when building CSS-in-JS libraries or inserting styles manually |
| When not to use it | In ordinary components (it blocks layout and is useless for logic) |

---

One-line summary:

> useInsertionEffect() is the "zero moment" for synchronously inserting styles before layout, needed only by libraries that manage CSS dynamically.

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

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.