🏯 PositionObserver is a JavaScript tool that provides a way to asynchronously observe changes in the position of a target element within its viewport.
npm install @thednp/position-observer
The PositionObserver is a lightweight utility that replaces traditional resize and scroll event listeners. Built on the IntersectionObserver API, it provides a way to asynchronously observe changes in the position of a target element with an ancestor element or with a top-level document's viewport.
``bash`
npm i @thednp/position-observer
`bash`
yarn add @thednp/position-observer
`bash`
pnpm add @thednp/position-observer
`bash`
deno add npm:@thednp/position-observer@latest
`ts
import PositionObserver from '@thednp/position-observer';
// Find a target element
const myTarget = document.getElementById('myElement');
// Define a callback
const callback = (entries: IntersectionObserverEntry[], currentObserver: PositionObserver) => {
// Access the observer inside your callback
// console.log(currentObserver);
entries.forEach((entry) => {
if (entry.isIntersecting/ and your own conditions apply /) {
// Handle position changes
console.log(entry.boundingClientRect);
}
})
};
// Set options
const options = {
root: document.getElementById('myModal'), // Defaults to document.documentElement
rootMargin: '0px', // Margin around the root, this applies to IntersectionObserver only
threshold: 0, // Trigger when any part of the target is visible, this applies to IntersectionObserver only
callbackMode: 'intersecting', // Options: 'all', 'intersecting', 'update'
};
// Create the observer
const observer = new PositionObserver(callback, options);
// Start observing
observer.observe(myTarget);
// Example callback entries
[{
target:
boundingClientRect: DOMRectReadOnly,
intersectionRatio: number,
isIntersecting: boolean,
// ... other IntersectionObserverEntry properties
}]
// Get an entry
observer.getEntry(myTarget);
// Stop observing a target
observer.unobserve(myTarget);
// Resume observing
observer.observe(myTarget);
// Stop all observation
observer.disconnect();
`
| Option | Type | Description |
|--------| -----|-------------|
| root | Element \| undefined | The element used as the viewport for checking target visibility. Defaults to document.documentElement.|callbackMode
| | "all" \| "intersecting" \| "update" \| undefined | Controls PositionObserver callback behavior. Defaults to "intersecting". See below for details. |rootMargin
| | string \| undefined | Margin around the root of the IntersectionObserver. Uses same format as CSS margins (e.g., "10px 20px"). |threshold
| | number \| number[] \| undefined | Percentage of the target's visibility required to trigger the IntersectionObserver callback. |
identifies the Element whose bounds are treated as the bounding box of the viewport for the element which is the observer's target. Since we're observing for its width and height changes, this root can only be an instance of Element, so Document cannot be the root of your PositionObserver instance.The IntersectionObserver
instance.root is always the default, which is Document. The two observers really care for different things: one cares about intersection the other cares about position, which is why the two observers cannot use the same root.When observing targets from a scrollable parent element, that parent must be set as root. The same applies to embeddings and
IFrames. See the ScrollSpy example for implementation details.$3
The two initialization options specifically for the IntersectionObserver are rootMargin and threshold and only apply when using "intersecting" or "update" modes.$3
* all: Triggers the callback for all observed targets, regardless of visibility or position changes.
* intersecting: Triggers the callback only for targets that are intersecting with the document's viewport and have changed position or root dimensions.
* update: Triggers the callback for targets with position/root dimension changes or when a target's intersection status changes (e.g., from intersecting to non-intersecting).
How it Works
* Initialization: Requires a valid callback function, or it throws an Error.
* Target Validation: The observe() method requires a valid Element, or it throws an Error. Targets not attached to the DOM are ignored.
* Observation: Tracks changes in the target's top or left position relative to the root, as well as the root's clientWidth and clientHeight.
* Callback Trigger: The callback is invoked based on the callbackMode:
- all: Includes every observed target's entry.
- intersecting: Includes only intersecting targets with position or root dimension changes.
- update: Includes targets with position/root dimension changes or a change in intersection status.
* Intersection Checks: Uses IntersectionObserver with the document as the root to determine isIntersecting. The rootMargin and threshold options apply to these checks but have no impact in all mode.
Notes
* Performance: Use entry.boundingClientRect from observer.getEntry(target) to avoid redundant getBoundingClientRect() calls.
* Async Design: Leverages requestAnimationFrame and IntersectionObserver for efficient, asynchronous operation. Consider wrapping callbacks in requestAnimationFrame for synchronization and to eliminate any potential observation errors.
* Visibility: Targets must be visible (no display: none or visibility: hidden) for actual accurate bounding box measurements.
* Cleanup: Call unobserve() or disconnect() when observation is no longer needed to free resources.
* ResizeObserver Alternative: Filter callbacks on entry.boundingClientRect.width or height changes to mimic ResizeObserver.
* Scroll Optimization: For scroll-specific changes, filter callbacks on entry.boundingClientRect.top or left.
* IntersectionObserver Root: The underlying IntersectionObserver uses the document as its root, while the PositionObserver's root option defines the reference Element for position tracking.
* IntersectionObserverEntry Spread: This is an interface instance and cannot be spread.
* Callback Mode Selection: Choose callbackMode based on your use case:
- Use intersecting for most scenarios where only visible elements matter.
- Use update to track intersection state changes.
- Use all for comprehensive monitoring of all targets.
* RootMargin and Threshold: These options have no impact in all mode, as non-intersecting targets are still processed. They are however relevant in intersecting or update` modes for defining visibility conditions.