useElementSize
Tracks the size of an element with a ResizeObserver and returns its width
and height as state. Attach the returned ref to any element and your
component re-renders only when that element's size actually changes.
When to use it
- Making layout decisions from a container's width instead of the viewport's.
- Sizing a chart, canvas or virtual list to the space it is given.
- Showing or hiding content (truncation, "show more") based on available space.
- Building your own helpers (
useIsNarrow,useAspectRatio, ...) on top.
Demo
Edit the code below — the preview re-runs live. Drag the bottom-right corner of
each box to resize it, and open the Console tab to see the onResize
callback.
Loading demo…
Signature
interface ElementSize {
width: number;
height: number;
}
interface UseElementSizeOptions {
box?: "content-box" | "border-box";
defaultSize?: ElementSize;
onResize?: (size: ElementSize, entry: ResizeObserverEntry) => void;
}
interface UseElementSizeResult<T extends Element> extends ElementSize {
ref: (element: T | null) => void;
}
function useElementSize<T extends Element = HTMLElement>(
options?: UseElementSizeOptions
): UseElementSizeResult<T>;
| Option | Type | Description |
|---|---|---|
box | "content-box" | "border-box" | Which box to measure. Defaults to "content-box"; "border-box" includes padding and border. |
defaultSize | { width: number; height: number } | Size used on the server and until the first measurement. Only read on first render. Defaults to 0 x 0. |
onResize | (size, entry: ResizeObserverEntry) => void | Called when the measured size changes, including the first measurement. The latest callback is used. |
Returns: an object with the width and height (in CSS pixels) and the
ref to attach to the element. The type parameter T is the element type, for
example useElementSize<HTMLDivElement>().
Usage notes
refis a callback ref, so it works when the element mounts later, is rendered conditionally, or is swapped for another one. It has a stable identity across renders.- The first measurement arrives after the element mounts, so the first render
(and the server render) uses
defaultSize. Pick a default that matches your server-rendered layout if the difference is visible. - Values are fractional CSS pixels, exactly as the browser reports them. Round
them yourself if you need whole numbers. CSS transforms such as
scale()do not affect them, and adisplay: noneelement measures0x0. - The component re-renders only when
widthorheightchanges.onResizeruns at the same moments, straight from the observer, so use it for side effects instead of copying the size into state. Its second argument is the rawResizeObserverEntry, in case you needcontentRector the other boxes. - Changing
boxre-observes the element.onResizecan change freely without re-observing. - When the element unmounts, the observer is disconnected and the last measured size is kept. The observer is also disconnected when the component unmounts.
- Where
ResizeObserveris unavailable (older browsers, some test environments), the hook returnsdefaultSizeand never throws. - Observing an element whose size depends on the component's own render can
create a loop (for example, the content sets its size from
width). Browsers report this as aResizeObserver loopwarning. Keep the observed element's size independent of the measured values. - To combine it with another ref, call both from a function ref:
ref={(el) => { ref(el); myRef.current = el; }}. - Want the raw
ResizeObserverEntryand no state? UseuseResizeObserver. - Need to react to the viewport instead? Use
useMediaQuery. For custom DOM events, useuseEventListener.
Examples
const { ref, width, height } = useElementSize<HTMLDivElement>();
return (
<div ref={ref}>
{Math.round(width)} x {Math.round(height)}
</div>
);
// Include padding and border, and run a side effect on every change
const { ref } = useElementSize<HTMLElement>({
box: "border-box",
onResize: ({ width }) => analytics.track("panel-width", width),
});
// Compose your own helpers on top
const useIsNarrow = (limit: number) => {
const { ref, width } = useElementSize<HTMLDivElement>();
return { ref, isNarrow: width > 0 && width < limit };
};
// Share the element with another ref
const { ref: sizeRef, width } = useElementSize<HTMLDivElement>();
const containerRef = useRef<HTMLDivElement>(null);
return (
<div
ref={(el) => {
sizeRef(el);
containerRef.current = el;
}}
/>
);
Hook source
View useElementSize source
useElementSize sourceuse-element-size.ts
import { useEffect, useRef, useState } from "react";
import { useLatest } from "./use-latest";
/** The width and height of an element, in CSS pixels. */
export interface ElementSize {
width: number;
height: number;
}
/** Options for {@link useElementSize}. */
export interface UseElementSizeOptions {
/**
* Which box to measure.
*
* - `"content-box"` (default): the content area, excluding padding and border.
* - `"border-box"`: the content plus padding and border.
*/
box?: "content-box" | "border-box";
/**
* Size reported on the server and until the element has been measured.
* Only read on the first render. Defaults to `{ width: 0, height: 0 }`.
*/
defaultSize?: ElementSize;
/**
* Called from the resize observer whenever the measured size changes,
* including the first measurement. Receives the new size and the raw
* `ResizeObserverEntry`, for example to read `contentRect` or the other
* boxes. The latest callback is always used.
*/
onResize?: (size: ElementSize, entry: ResizeObserverEntry) => void;
}
/** The object returned by {@link useElementSize}. */
export interface UseElementSizeResult<T extends Element> extends ElementSize {
/** Attach this to the element you want to measure, as its `ref`. */
ref: (element: T | null) => void;
}
const ZERO_SIZE: ElementSize = { width: 0, height: 0 };
const readSize = (
entry: ResizeObserverEntry,
box: "content-box" | "border-box"
): ElementSize => {
if (box === "content-box") {
// `contentRect` is physical (width/height), unlike `contentBoxSize`.
return { width: entry.contentRect.width, height: entry.contentRect.height };
}
const borderBox = entry.borderBoxSize?.[0];
if (!borderBox) {
const rect = entry.target.getBoundingClientRect();
return { width: rect.width, height: rect.height };
}
// `borderBoxSize` is logical: inline/block swap in vertical writing modes.
const vertical = /^(vertical|sideways)/.test(
getComputedStyle(entry.target).writingMode
);
return vertical
? { width: borderBox.blockSize, height: borderBox.inlineSize }
: { width: borderBox.inlineSize, height: borderBox.blockSize };
};
/**
* Tracks the size of an element with a `ResizeObserver` and returns it as
* state, so your component re-renders when the element is resized.
*
* - **Usage:** attach the returned `ref` to any element. It is a callback ref,
* so it also works when the element mounts later, is rendered conditionally,
* or is swapped for another one.
* - **Efficient:** re-renders only when the width or height actually changes.
* - **Box:** measures the content box by default; pass `box: "border-box"` to
* include padding and border.
* - **Values:** fractional CSS pixels, exactly as reported by the browser.
* CSS transforms do not affect them. A `display: none` element measures
* `0` x `0`.
* - **SSR-safe:** returns `defaultSize` on the server, on the first render, and
* wherever `ResizeObserver` is unavailable.
* - **Cleanup:** the observer is disconnected on unmount and when the element
* or `box` changes. When the element unmounts, the last measured size is kept.
*
* The first measurement arrives after the element mounts, so the first render
* (and the server render) uses `defaultSize`. To combine with another ref, call
* both from a function ref, for example `ref={(el) => { ref(el); myRef.current = el; }}`.
*
* @typeParam T - The type of element being measured. Defaults to `HTMLElement`.
* @param options - Optional `box`, `defaultSize` and `onResize` callback.
* @returns The element's `width` and `height`, and the `ref` to attach to it.
*
* @example
* ```tsx
* const { ref, width, height } = useElementSize<HTMLDivElement>();
*
* return (
* <div ref={ref}>
* {Math.round(width)} x {Math.round(height)}
* </div>
* );
* ```
*
* @example
* ```tsx
* // Include padding and border, and react to every change
* const { ref } = useElementSize<HTMLElement>({
* box: "border-box",
* onResize: ({ width }) => console.log("new width", width),
* });
* ```
*
* @example
* ```tsx
* // Compose your own helpers on top
* const useIsNarrow = (limit: number) => {
* const { ref, width } = useElementSize<HTMLDivElement>();
* return { ref, isNarrow: width > 0 && width < limit };
* };
* ```
*
* For a live, editable example, see the [useElementSize docs page](https://altalyst-solutions.github.io/hookify/hooks/use-element-size).
*
* @see [ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)
*/
export const useElementSize = <T extends Element = HTMLElement>(
options?: UseElementSizeOptions
): UseElementSizeResult<T> => {
const box = options?.box ?? "content-box";
const onResizeRef = useLatest(options?.onResize);
const [element, setElement] = useState<T | null>(null);
const [size, setSize] = useState<ElementSize>(
() => options?.defaultSize ?? ZERO_SIZE
);
// Last reported size, so identical measurements neither re-render nor
// call `onResize` (for example when StrictMode observes the element twice).
const lastSizeRef = useRef(size);
useEffect(() => {
if (!element || typeof ResizeObserver === "undefined") return;
const observer = new ResizeObserver((entries) => {
const entry = entries[entries.length - 1];
if (!entry) return;
const next = readSize(entry, box);
const last = lastSizeRef.current;
if (next.width === last.width && next.height === last.height) return;
lastSizeRef.current = next;
setSize(next);
onResizeRef.current?.(next, entry);
});
observer.observe(element, { box });
return () => observer.disconnect();
}, [element, box, onResizeRef]);
return { ref: setElement, width: size.width, height: size.height };
};