🪝 Introduction to useInsertionEffect
The useInsertionEffect Hook is a specialized React Hook designed primarily for CSS-in-JS libraries. It allows styles to be inserted into the DOM before layout effects execute, ensuring that components are rendered with the correct styles from the very beginning.
Important
🎯 Why Use useInsertionEffect?
Modern styling libraries often generate CSS dynamically while components render. Without a dedicated mechanism, styles may be inserted too late, causing layout shifts or a brief flash of unstyled content. useInsertionEffect ensures that styles are available before layout calculations occur.
- Insert dynamically generated CSS.
- Prevent flashes of unstyled content (FOUC).
- Ensure layout measurements use the correct styles.
- Support CSS-in-JS libraries efficiently.
⚙️ Syntax
Basic Syntax
useInsertionEffect(() => {
// Insert styles
return () => {
// Cleanup (optional)
};
}, [dependencies]);| Part | Description |
|---|---|
| Effect Function | Runs before layout effects. |
| Cleanup Function | Runs before the next insertion effect or component unmount. |
| Dependency Array | Controls when the insertion effect executes. |
🔄 Execution Order
💻 Basic Example
Using useInsertionEffect
import { useInsertionEffect } from "react";
function Example() {
useInsertionEffect(() => {
console.log("Insert styles here");
}, []);
return <div>Hello React</div>;
}In this example, the insertion effect runs before any layout effects, making it suitable for injecting dynamically generated CSS into the document.
🎨 Example: Injecting a Style Element
Style Injection
import { useInsertionEffect } from "react";
function StyledComponent() {
useInsertionEffect(() => {
const style = document.createElement("style");
style.textContent = ".title { color: blue; }";
document.head.appendChild(style);
return () => {
document.head.removeChild(style);
};
}, []);
return <h1 className="title">Hello</h1>;
}This example demonstrates the basic concept of inserting styles before layout effects. In practice, CSS-in-JS libraries perform this process automatically.
📊 Comparing Effect Hooks
| Hook | When It Runs | Typical Purpose |
|---|---|---|
| useInsertionEffect | Before layout effects. | Insert generated CSS. |
| useLayoutEffect | Before browser paint. | Measure or update the layout. |
| useEffect | After browser paint. | Fetch data, timers, subscriptions. |
📅 React Rendering Timeline
React renders the component.
React updates the DOM.
useInsertionEffect inserts generated styles.
useLayoutEffect measures or adjusts the layout.
The browser paints the updated interface.
useEffect executes after the browser has painted.
🎯 Common Use Cases
Dynamically generate and insert CSS rules before layout calculations.
Build styling libraries that manage CSS efficiently during rendering.
Most React applications do not need this Hook directly because styling libraries handle it internally.
Ensure styles are available before layout measurements to avoid visual inconsistencies.
⚠️ When Not to Use useInsertionEffect
- Fetching data from APIs.
- Setting timers or intervals.
- Reading or measuring DOM elements.
- Handling user interactions.
- General application side effects.
Warning
✅ Best Practices
- Use useInsertionEffect only for CSS insertion.
- Keep insertion logic lightweight and synchronous.
- Prefer useEffect for ordinary side effects.
- Use useLayoutEffect for layout measurements instead of style insertion.
- Rely on CSS-in-JS libraries to use this Hook internally whenever possible.
📚 Official Resource
Learn more about useInsertionEffect in the official React documentation at React useInsertionEffect Documentation.