npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@html-ng/bounding-client-rect-observer

v0.1.3

Published

A polyfill for the `BoundingClientRectObserver`

Downloads

7,491

Readme

bounding-client-rect-observer

A polyfill for the BoundingClientRectObserver.

This observer notifies you when the bounds returned by Element.getBoundingClientRect() change.

Please note that this is a best-effort solution. See Known Limitations.

Installation

npm install @html-ng/bounding-client-rect-observer

Examples

Basic Example

This example demonstrates how to create a new BoundingClientRectObserver instance and start observing an element's bounding client rect.

import { BoundingClientRectObserver } from '@html-ng/bounding-client-rect-observer';

const elementToObserve = document.querySelector('#my-element');

const callback = (entries, observer) => {
    entries.forEach((entry) => {
        const {target, previousBounds, newBounds} = entry;
        console.log({target, previousBounds, newBounds});
    });
};

const observer = new BoundingClientRectObserver(callback);

observer.observe(elementToObserve);

// Remember to disconnect the observer when it's no longer needed
// observer.disconnect();

Multiple Elements

This example demonstrates how to observe multiple elements using a single BoundingClientRectObserver instance.

This approach aligns with the organization of other members of the observer class family. In the future, it may provide performance benefits compared to creating a separate instance for each observed element.

import { BoundingClientRectObserver, BoundingClientRectObserverCallback } from '@html-ng/bounding-client-rect-observer';

const elementsToObserve = document.querySelectorAll('.elements-to-observe');

const callback: BoundingClientRectObserverCallback = (entries, observer) => {
    entries.forEach((entry) => {
        const {target, previousBounds, newBounds} = entry;
        console.log({target, previousBounds, newBounds});
    });
};

const observer = new BoundingClientRectObserver(callback);

elementsToObserve.forEach((element) => {
    observer.observe(element);
});

// Remember to disconnect the observer when it's no longer needed
// observer.disconnect();

API Documentation

BoundingClientRectEntry

An object representing a single notification entry for an observed element when its bounding client rect changes. Properties:

  • target: Element: The observed element whose bounding client rect has changed.
  • previousBounds: DOMRectReadOnly: The previous bounding client rect of the element before the change.
  • newBounds: DOMRectReadOnly: The new bounding client rect of the element after the change.

BoundingClientRectObserverCallback

Signature:

(entries: ReadonlyArray<BoundingClientRectEntry>, observer: BoundingClientRectObserver) => void

A callback function that will be invoked when one or more observed elements have a change in their bounding client rects. Arguments:

  • entries: ReadonlyArray<BoundingClientRectEntry>: An array of BoundingClientRectEntry objects, each representing a single observed element whose bounding client rect has changed.

  • observer: BoundingClientRectObserver: The instance of BoundingClientRectObserver that triggered the callback. This can be useful if you have multiple observers and want to identify which observer the entries belong to.

class BoundingClientRectObserver

The main class for creating an observer to watch for changes in the bounding client rects of specified elements.

constructor(callback: BoundingClientRectObserverCallback)

Arguments:

  • callback: BoundingClientRectObserverCallback: The callback function that will be invoked when a bounding client rect change is detected in one or more observed elements.

observe(element: Element)

Starts observing the specified element's bounding client rect. If the element is already being observed, this method does nothing. Arguments:

  • element: Element: The element whose bounding client rect you want to observe.

disconnect()

Stops observing all elements and removes all observers.

Known Limitations

This utility is designed with a focus on simplicity and performance, which means that it may not cover every possible case. It is recommended to test this utility with your application to ensure it meets your requirements.

  1. CSS animations: The current implementation does not support CSS animations. As a result, you will not receive notifications for elements with CSS animations. However, adding support for this should be relatively straightforward.

  2. Inline elements affected by text layout: Elements that are affected by the layout of nearby text may not be fully supported, causing notifications to be delivered only part of the time. Improving support for this scenario should be possible.

  3. Static DOM tree assumption: The utility assumes that the element's path in the DOM tree remains static while it is being observed. This means that neither the observed element nor any of its ancestors should be detached from their respective parents. If an element is re-attached, you may start missing notifications. Addressing this limitation could be challenging.

License

Apache License 2.0