element-bounding

Track an element's getBoundingClientRect() reactively.


Package	`@vizejs/composable/element-bounding`
Own the source	`vize lib pull composable:element-bounding`
Runtime exports	`useElementBounding`
Gzip budget	3840 B

Usage

import { useElementBounding } from "@vizejs/composable/element-bounding";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useElementBounding`	dom	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	`window`	`resolveElement`, `useEventListener`, `useResizeObserver`, `tryOnScopeDispose`

API

`useElementBounding`

Track an element's getBoundingClientRect() reactively. Measures when the target resolves, when it resizes (via ResizeObserver), and — unless disabled — when the window resizes or anything scrolls. Every value is 0 during server rendering and before the first measurement, so the initial render is hydration-stable. Listeners and the observer are released with the owning reactive scope.

function useElementBounding( target: MaybeElementTarget, options: UseElementBoundingOptions = {}, ): ElementBoundingControls

Types

`ElementBoundingHost`

Window-like capability observed by useElementBounding: scroll and resize events plus the optional ResizeObserver constructor.

Member	Type	Description
`ResizeObserver`?	`new (callback: ResizeObserverCallback) => ResizeObserver`	`ResizeObserver` constructor, absent in unsupported runtimes.

`ElementBoundingRect`

Viewport-relative element geometry in CSS pixels.

Member	Type	Description
`x`	`number`	Horizontal position of the border box origin.
`y`	`number`	Vertical position of the border box origin.
`top`	`number`	Distance from the viewport top edge to the border box top edge.
`right`	`number`	Distance from the viewport left edge to the border box right edge.
`bottom`	`number`	Distance from the viewport top edge to the border box bottom edge.
`left`	`number`	Distance from the viewport left edge to the border box left edge.
`width`	`number`	Border box width.
`height`	`number`	Border box height.

`UseElementBoundingOptions`

Options for useElementBounding.

Member	Type	Description
`reset`?	`boolean`	Reset every value to zero when the target unmounts.
`windowResize`?	`boolean`	Re-measure when the window resizes.
`windowScroll`?	`boolean`	Re-measure when any ancestor (or the window) scrolls. Uses a capturing, passive listener so nested scroll containers are covered.
`host`?	`MaybeRefOrGetter<ElementBoundingHost \| null \| undefined>`	Reactive window capability for alternate runtimes and tests.
`flush`?	`"pre" \| "post" \| "sync"`	Target resolution timing. `"post"` measures template refs after mount.