Skip to main content

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 server warning 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.

Loading demo…

Signature​

const useIsomorphicLayoutEffect: typeof useLayoutEffect;

// i.e.
function useIsomorphicLayoutEffect(
effect: EffectCallback,
deps?: DependencyList
): void;
ParameterTypeDescription
effectEffectCallbackThe effect to run. May return a cleanup function.
depsDependencyListOptional. 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 is useLayoutEffect itself, not a wrapper, so there is no extra overhead.

  • Chosen once, at module load. It uses useLayoutEffect when window and window.document.createElement exist, and useEffect otherwise (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 useEffect when you can. Layout effects block painting, so use this hook only when you must read or write layout before the paint. Otherwise use useEffect.

  • Linting. react-hooks/exhaustive-deps does not check custom hooks by default. To have it check this one, add it to additionalHooks:

    "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

use-isomorphic-layout-effect.ts
import { 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;