intersection-observer

Observe the intersection of reactive elements with a root.


Package	`@vizejs/composable/intersection-observer`
Own the source	`vize lib pull composable:intersection-observer`
Runtime exports	`useIntersectionObserver`, `useElementVisibility`
Gzip budget	2816 B

Usage

import { useIntersectionObserver, useElementVisibility } from "@vizejs/composable/intersection-observer";

Runtime contract

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

API

`useIntersectionObserver`

Observe the intersection of reactive elements with a root. One observer is created per combination of resolved targets, root, margin, and threshold; changing any of them disconnects the previous observer first. During server rendering isSupported is false and the callback never runs. The observer is disconnected when the owning scope stops.

function useIntersectionObserver( targets: MaybeElementTargets, callback: IntersectionObserverCallback, options: UseIntersectionObserverOptions = {}, ): IntersectionObserverControls

`useElementVisibility`

Track whether an element is visible inside the viewport (or a root). Uses the latest intersection entry, so rapid enter/leave sequences settle on the final state. With once, the observer disconnects after the first visible entry and isVisible stays true.

function useElementVisibility( target: MaybeElementTarget, options: UseElementVisibilityOptions = {}, ): ElementVisibilityControls

Types

`IntersectionObserverHost`

Runtime capability that supplies the IntersectionObserver constructor.

Member	Type	Description
`IntersectionObserver`?	`new ( callback: IntersectionObserverCallback, options?: IntersectionObserverInit, ) => IntersectionObserver`	`IntersectionObserver` constructor, absent in unsupported runtimes.

`UseIntersectionObserverOptions`

Options for useIntersectionObserver.

Member	Type	Description
`root`?	`IntersectionRoot`	Ancestor (or document) whose box is used as the viewport.
`rootMargin`?	`MaybeRefOrGetter<string>`	Margin grown or shrunk around the root box, in CSS margin syntax.
`threshold`?	`MaybeRefOrGetter<number \| readonly number[]>`	Visible-ratio thresholds that trigger the callback.
`immediate`?	`boolean`	Start observing during composable creation. When `false`, call `resume`.
`host`?	`MaybeRefOrGetter<IntersectionObserverHost \| null \| undefined>`	Reactive constructor capability for alternate runtimes and tests.
`flush`?	`"pre" \| "post" \| "sync"`	Target resolution timing. `"post"` observes template refs after mount.

`IntersectionObserverControls`

Controls returned by useIntersectionObserver.

Member	Type	Description
`isSupported`	`Readonly<Ref<boolean>>`	Whether the host provides `IntersectionObserver`. `false` during server rendering.
`isActive`	`Readonly<Ref<boolean>>`	Whether observation is currently requested (not paused or stopped).
`pause`	`() => void`	Disconnect the observer while keeping the ability to `resume`.
`resume`	`() => void`	Reconnect after `pause` (or start when created with `immediate: false`).
`stop`	`() => void`	Disconnect permanently. Later `resume` calls are ignored. Idempotent.

`UseElementVisibilityOptions`

Options for useElementVisibility.

Member	Type	Description
`initialValue`?	`boolean`	Visibility exposed before the first observation and during server rendering. Keep it identical on server and client.
`once`?	`boolean`	Stop observing after the element becomes visible for the first time.

`ElementVisibilityControls`

Reactive state returned by useElementVisibility.

Member	Type	Description
`isVisible`	`Readonly<Ref<boolean>>`	Whether the element currently intersects the root.
`isSupported`	`Readonly<Ref<boolean>>`	Whether the host provides `IntersectionObserver`.
`stop`	`() => void`	Stop observing. Idempotent.