Elements

useElementBounding

Tracks the bounding rect of a DOM element — x, y, top, right, bottom, left, width, height — as reactive Observable<number> values. Uses ResizeObserver for size changes, MutationObserver for style/class attribute changes, and scroll/resize window events for position changes. requestAnimationFrame is used by default so CSS transform animations are captured accurately.

Demo

Element Bounding

Resize the box below to see its bounding rect update.

0px

top

0px

left

0px

width

0px

height

0px

resize me ↘

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 useElementBounding: (target: MaybeEventTarget, options?: DeepMaybeObservable<UseElementBoundingOptions>) => UseElementBoundingReturn
useElementBounding } 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 top$: any
top$, 
const left$: any
left$, 
const width$: any
width$, 
const height$: any
height$ } = 
function useElementBounding(target: MaybeEventTarget, options?: DeepMaybeObservable<UseElementBoundingOptions>): UseElementBoundingReturn
Framework-agnostic bounding-rect tracker. Must be called inside a useScope
factory — ResizeObserver / MutationObserver / window listeners are registered
via the scope-aware create* helpers and are cleaned up automatically when
the scope disposes. Public API matches the legacy useElementBounding hook.
useElementBounding(
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()} at ({
const left$: any
left$.
any
get()}, {
const top$: any
top$.
any
get()})
    </
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div>
  );
}

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

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

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

Manual update

// @noErrors
import { useRef$, Ref$ } from "@usels/core";
import { useElementBounding } from "@usels/web";
declare const el$: Ref$<HTMLDivElement>;
// ---cut---
const { top$, left$, update } = useElementBounding(el$);

// Force-recalculate bounding rect imperatively
update();

Disable window scroll tracking

const { top$, left$ } = useElementBounding(el$, { windowScroll: false });

Skip requestAnimationFrame (synchronous reads)

const { width$, height$ } = useElementBounding(el$, { useCssTransforms: false });

Keep values on unmount (no reset)

const { top$ } = useElementBounding(el$, { reset: false });

Type

Parameters

Parameter	Type	Description
`target`	`MaybeEventTarget`	-
`options`	`UseElementBoundingOptions` (optional)	-

UseElementBoundingOptions

Option	Type	Default	Description
`reset`	`boolean`	`-`	Reset all values to 0 when element unmounts. Default: true
`windowResize`	`boolean`	`-`	Re-calculate on window resize. Default: true
`windowScroll`	`boolean`	`-`	Re-calculate on window scroll. Default: true
`immediate`	`boolean`	`-`	Calculate immediately on mount. Default: true
`useCssTransforms`	`boolean`	`-`	Use requestAnimationFrame to read rect after CSS transforms settle. Default: true
`window`	`WindowSource`	`-`	-

Returns

UseElementBoundingReturn

Name	Type	Description
`x$`	`ObservablePrimitive<number>`	-
`y$`	`ObservablePrimitive<number>`	-
`top$`	`ObservablePrimitive<number>`	-
`right$`	`ObservablePrimitive<number>`	-
`bottom$`	`ObservablePrimitive<number>`	-
`left$`	`ObservablePrimitive<number>`	-
`width$`	`ObservablePrimitive<number>`	-
`height$`	`ObservablePrimitive<number>`	-
`update`	`() => void`	-

Source

View on GitHub