resize-observer

Observe size changes of one or more reactive elements.


Package	`@vizejs/composable/resize-observer`
Own the source	`vize lib pull composable:resize-observer`
Runtime exports	`useResizeObserver`, `useElementSize`
Gzip budget	2816 B

Usage

import { useResizeObserver, useElementSize } from "@vizejs/composable/resize-observer";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useResizeObserver`	dom	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	`globalThis`, `ResizeObserver`	`resolveElements`, `tryOnScopeDispose`
`useElementSize`	dom	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	`globalThis`, `ResizeObserver`	`useResizeObserver`, `resolveElement`, `tryOnScopeDispose`

API

`useResizeObserver`

Observe size changes of one or more reactive elements. A single observer is (re)created whenever the resolved targets, the box option, or the host change; unresolved targets are skipped. The observer is disconnected when the owning reactive scope stops or stop is called. During server rendering no host resolves, isSupported stays false, and the callback never runs. Inside a component the host is read after mounting, so hydration renders the server fallback first and never mismatches.

function useResizeObserver( targets: MaybeElementTargets, callback: ResizeObserverCallback, options: UseResizeObserverOptions = {}, ): ResizeObserverControls

`useElementSize`

Track the rendered size of a reactive element. Reads the requested box from contentBoxSize/borderBoxSize (summing fragments) and falls back to contentRect for older engines. When the target unmounts the size resets to the initial value so stale geometry never leaks into the next render. Server renders expose initialSize.

function useElementSize( target: MaybeElementTarget, options: UseElementSizeOptions = {}, ): ElementSizeControls

Types

`ResizeObserverHost`

Runtime capability that supplies the ResizeObserver constructor.

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

`UseResizeObserverOptions`

Options for useResizeObserver.

Member	Type	Description
`box`?	`ResizeObserverBoxOptions`	Box model reported by the observer.
`host`?	`MaybeRefOrGetter<ResizeObserverHost \| null \| undefined>`	Reactive constructor capability for alternate runtimes and tests.
`flush`?	`"pre" \| "post" \| "sync"`	Target resolution timing. `"post"` observes template refs after mount.

`ResizeObserverControls`

Controls returned by useResizeObserver.

Member	Type	Description
`isSupported`	`Readonly<Ref<boolean>>`	Whether the host provides `ResizeObserver`. `false` during server rendering.
`stop`	`() => void`	Disconnect the observer and stop following the reactive targets. Idempotent.

`ElementSize`

Element dimensions reported by useElementSize.

Member	Type	Description
`width`	`number`	Inline size in CSS pixels.
`height`	`number`	Block size in CSS pixels.

`UseElementSizeOptions`

Options for useElementSize.

Member	Type	Description
`box`?	`ResizeObserverBoxOptions`	Box model reported by the observer.
`host`?	`MaybeRefOrGetter<ResizeObserverHost \| null \| undefined>`	Reactive constructor capability for alternate runtimes and tests.
`flush`?	`"pre" \| "post" \| "sync"`	Target resolution timing. `"post"` observes template refs after mount.
`initialSize`?	`ElementSize`	Size exposed before the first observation and during server rendering. Keep it identical on server and client to avoid hydration mismatches.

`ElementSizeControls`

Reactive size returned by useElementSize.

Member	Type	Description
`isSupported`	`Readonly<Ref<boolean>>`	Whether the host provides `ResizeObserver`. `false` during server rendering.
`stop`	`() => void`	Disconnect the observer and stop following the reactive targets. Idempotent.
`width`	`Readonly<Ref<number>>`	Observed inline size in CSS pixels.
`height`	`Readonly<Ref<number>>`	Observed block size in CSS pixels.