useIsomorphicLayoutEffect
A drop-in replacement for useLayoutEffect that is safe in server-rendered
apps. In the browser it is useLayoutEffect; where there is no DOM it
falls back to useEffect.
When to use it
- Measuring or adjusting the DOM before the browser paints (sizing, positioning, scroll restoration) in code that also renders on the server, such as Next.js, Remix or Gatsby.
- Writing your own hooks or components that need layout timing and must work
in both client and server environments. This avoids the server-side
useLayoutEffect does nothing on the serverwarning in React 18.
Demo
Edit the code below — the preview re-runs live. Type in the textarea, then open the Console tab and click the button to see when each phase runs.
Signature
const useIsomorphicLayoutEffect: typeof useLayoutEffect;
// i.e.
function useIsomorphicLayoutEffect(
effect: EffectCallback,
deps?: DependencyList
): void;
| Parameter | Type | Description |
|---|---|---|
effect | EffectCallback | The effect to run. May return a cleanup function. |
deps | DependencyList | Optional. Controls when the effect re-runs, exactly as in React hooks. |
Returns: nothing, like useLayoutEffect.
Usage notes
-
Same API as
useLayoutEffect. The signature, timing, cleanup and dependency behavior are React's own, so you can swap it in anywhere, including inside your own hooks and libraries. It isuseLayoutEffectitself, not a wrapper, so there is no extra overhead. -
Chosen once, at module load. It uses
useLayoutEffectwhenwindowandwindow.document.createElementexist, anduseEffectotherwise (server rendering, React Native). Neither effect runs during server rendering; the fallback just avoids the React 18 warning. React 19 removed that warning, but the hook stays useful for apps supporting both versions. -
Hydration. The effect runs on the client after hydration like any other layout effect, so keep the first render identical on server and client and apply layout changes inside the effect.
-
Prefer
useEffectwhen you can. Layout effects block painting, so use this hook only when you must read or write layout before the paint. Otherwise useuseEffect. -
Linting.
react-hooks/exhaustive-depsdoes not check custom hooks by default. To have it check this one, add it toadditionalHooks:"react-hooks/exhaustive-deps": ["warn",{ additionalHooks: "(useIsomorphicLayoutEffect)" },] -
Safe under React
StrictMode.
Example
const ref = useRef<HTMLTextAreaElement>(null);
useIsomorphicLayoutEffect(() => {
const el = ref.current;
if (!el) return;
el.style.height = "auto";
el.style.height = `${el.scrollHeight}px`;
}, [value]);
return <textarea ref={ref} value={value} onChange={onChange} />;
Hook source
View useIsomorphicLayoutEffect source
useIsomorphicLayoutEffect sourceimport { useEffect, useLayoutEffect } from "react";
// `window.document.createElement` also rules out environments such as React
// Native, which define `window` but have no DOM.
const canUseDOM =
typeof window !== "undefined" &&
typeof window.document?.createElement === "function";
/**
* A drop-in replacement for `useLayoutEffect` that is safe to use in
* server-rendered apps.
*
* In the browser it is `useLayoutEffect`: the effect runs synchronously after
* React updates the DOM and before the browser paints, so you can measure or
* adjust the layout without a visible flicker. Where there is no DOM (server
* rendering, React Native) it falls back to `useEffect`. Neither runs during
* server rendering, but `useLayoutEffect` triggers a warning there in
* React 18, which this avoids.
*
* It has exactly the same signature and semantics as `useLayoutEffect`, so it
* can be swapped in anywhere, including inside your own hooks. The choice is
* made once, when the module loads.
*
* To have `react-hooks/exhaustive-deps` check its dependencies, add it to the
* rule's `additionalHooks` option.
*
* @param effect - The effect to run. May return a cleanup function.
* @param deps - Dependencies that control when the effect re-runs, as with `useLayoutEffect`.
*
* @example
* ```tsx
* const ref = useRef<HTMLTextAreaElement>(null);
*
* useIsomorphicLayoutEffect(() => {
* const el = ref.current;
* if (!el) return;
* el.style.height = "auto";
* el.style.height = `${el.scrollHeight}px`;
* }, [value]);
* ```
*/
export const useIsomorphicLayoutEffect: typeof useLayoutEffect = canUseDOM
? useLayoutEffect
: useEffect;