Skip to content

useElementSize

Tracks the width and height of a DOM element using the ResizeObserver API. Returns reactive Observable<number> values that update whenever the element resizes. SVG elements use getBoundingClientRect() as a fallback. Supports all three box models.

Demo

width: 0pxheight: 0px

Usage

import { 
function useRef$<T extends Element = Element>(externalRef?: React.Ref<T> | null): Ref$<T>
Creates an observable element ref. Can be used as a drop-in replacement for
useRef, composed with callback refs, or used with forwardRef.
The element is wrapped with opaqueObject to prevent legendapp/state
from making DOM properties reactive (deep observation).
@param ― externalRef - Optional. Accepts callback ref, RefObject, or null (forwardRef compatible).
@returns ― A callable ref that is also observable via get/peek
@example 
// standalone — useRef replacement
const el$ = useRef$<HTMLDivElement>();
return <div ref={el$} />;

// forwardRef compatible
const Component = forwardRef<HTMLDivElement>((props, ref) => {
  const el$ = useRef$(ref);
  return <div ref={el$} />;
});

// callback ref composition
const myRef = useCallback((node: HTMLDivElement | null) => {
  node?.focus();
}, []);
const el$ = useRef$(myRef);
return <div ref={el$} />;
useRef$, 
import useElementSize
useElementSize } from "@usels/core";

function 
function Component(): React.JSX.Element
Component() {
  const 
const el$: Ref$<HTMLDivElement>
el$ = 
useRef$<HTMLDivElement>(externalRef?: React.Ref<HTMLDivElement> | undefined): Ref$<HTMLDivElement>
Creates an observable element ref. Can be used as a drop-in replacement for
useRef, composed with callback refs, or used with forwardRef.
The element is wrapped with opaqueObject to prevent legendapp/state
from making DOM properties reactive (deep observation).
@param ― externalRef - Optional. Accepts callback ref, RefObject, or null (forwardRef compatible).
@returns ― A callable ref that is also observable via get/peek
@example 
// standalone — useRef replacement
const el$ = useRef$<HTMLDivElement>();
return <div ref={el$} />;

// forwardRef compatible
const Component = forwardRef<HTMLDivElement>((props, ref) => {
  const el$ = useRef$(ref);
  return <div ref={el$} />;
});

// callback ref composition
const myRef = useCallback((node: HTMLDivElement | null) => {
  node?.focus();
}, []);
const el$ = useRef$(myRef);
return <div ref={el$} />;
useRef$<
interface HTMLDivElement
HTMLDivElement>();
  const { 
const width$: any
width$, 
const height$: any
height$ } = 
import useElementSize
useElementSize(
const el$: Ref$<HTMLDivElement>
el$);

  return (
    <
React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div 
React.RefAttributes<HTMLDivElement>.ref?: React.Ref<HTMLDivElement> | undefined
Allows getting a ref to the component instance.
Once the component unmounts, React will set ref.current to null
(or call the ref with null if you passed a callback ref).
@see ― https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs
ref={
const el$: Ref$<HTMLDivElement>
el$}>
      {
const width$: any
width$.
any
get()} × {
const height$: any
height$.
any
get()}
    </
React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div>
  );
}

Custom initial size

const { 
const width$: any
width$, 
const height$: any
height$ } = 
import useElementSize
useElementSize(
const el$: Ref$<HTMLDivElement>
el$, { 
width: number
width: 320, 
height: number
height: 240 });

With `border-box`

const { 
const width$: any
width$, 
const height$: any
height$ } = 
import useElementSize
useElementSize(
const el$: Ref$<HTMLDivElement>
el$, 
var undefined
undefined, { 
box: string
box: "border-box" });

Stopping observation manually

const { 
const width$: any
width$, 
const height$: any
height$, 
const stop: any
stop } = 
import useElementSize
useElementSize(
const el$: Ref$<HTMLDivElement>
el$);

const stop: any
stop();

Type Declarations

export interface UseElementSizeOptions {
    box?: "content-box" | "border-box" | "device-pixel-content-box";
}
export interface UseElementSizeReturn {
    width$: Observable<number>;
    height$: Observable<number>;
    stop: () => void;
}
export declare function useElementSize(target: MaybeElement, initialSize?: {
    width: number;
    height: number;
}, options?: UseElementSizeOptions): UseElementSizeReturn;

Source

Contributors

tigerwest

Changelog

a7392ab 2026-03-06 - feat(core,browser): add sync strategy hooks (tigerwest)