Elements

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

Element Size

Resize the textarea to see width & height update.

width

0px

height

0px

import { 
const useRef$: {
    <T = any>(initialValue: null): Ref$<T | null>;
    <T = any>(initialValue: T): Ref$<T>;
    <T = any>(): Ref$<T | null>;
}
useRef$ } from "@usels/core";
import { 
const useElementSize: (target: MaybeEventTarget, initialSize?: {
    width: number;
    height: number;
}, options?: DeepMaybeObservable<UseElementSizeOptions>) => UseElementSizeReturn
useElementSize } from "@usels/web";

function 
function Component(): JSX.Element
Component() {
  const 
const el$: Ref$<HTMLDivElement | null>
el$ = 
useRef$<HTMLDivElement>(): Ref$<HTMLDivElement | null> (+2 overloads)
Core (framework-agnostic) version of useRef$.
Creates an observable element ref with opaque wrapping.

non-null value → Ref$<T>: current, get(), peek() return T
null / no arg → Ref$<T | null>: current, get(), peek() return T | null

Nullability is expressed via the type parameter, mirroring T | null at the call site.
useRef$<
interface HTMLDivElement
HTMLDivElement>();
  const { 
const width$: any
width$, 
const height$: any
height$ } = 
function useElementSize(target: MaybeEventTarget, initialSize?: {
    width: number;
    height: number;
}, options?: DeepMaybeObservable<UseElementSizeOptions>): UseElementSizeReturn
Framework-agnostic reactive element size tracker.
Tracks the width and height of a DOM element using ResizeObserver.
SVG elements use getBoundingClientRect() as fallback.
@param ― target - Element to observe (Ref$, Observable element, Document, Window, or null).
@param ― initialSize - Initial size values. Default { width: 0, height: 0 }.
@param ― options - Optional box model option.
@returns ― { width$, height$, stop } — reactive size observables and manual stop.
useElementSize(
const el$: Ref$<HTMLDivElement | null>
el$);

  return (
    <
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div 
RefAttributes<HTMLDivElement>.ref?: 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 | null>
el$}>
      {
const width$: any
width$.
any
get()} × {
const height$: any
height$.
any
get()}
    </
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div>
  );
}

import { createRef$ } from "@usels/core";
import { createElementSize } from "@usels/web";

function Component() {
  "use scope"
  const el$ = createRef$<HTMLDivElement>();
  const { width$, height$ } = createElementSize(el$);

  return (
    <div ref={el$}>
      {width$.get()} × {height$.get()}
    </div>
  );
}

Custom initial size

Hook
Scope

useElementSize(el$, { width: 320, height: 240 });

createElementSize(el$, { width: 320, height: 240 });

With `border-box`

Hook
Scope

useElementSize(el$, undefined, { box: "border-box" });

createElementSize(el$, undefined, { box: "border-box" });

Stopping observation manually

Hook
Scope

const { width$, height$, stop } = useElementSize(el$);

stop();

const { width$, height$, stop } = createElementSize(el$);

stop();

Type

Parameters

Parameter	Type	Description
`target`	`MaybeEventTarget`	- Element to observe (Ref$, Observable element, Document, Window, or null).
`initialSize`	`{ width: number; height: number; } \| undefined` (optional)	- Initial size values. Default `{ width: 0, height: 0 }`.
`options`	`UseElementSizeOptions` (optional)	- Optional box model option.

UseElementSizeOptions

Option	Type	Default	Description
`box`	`"content-box" \| "border-box" \| "device-pixel-content-box"`	`-`	-

Returns

UseElementSizeReturn

Name	Type	Description
`width$`	`ObservablePrimitive<number>`	-
`height$`	`ObservablePrimitive<number>`	-
`stop`	`() => void`	-

Source

View on GitHub