An API that provides a way to asynchronously observe the connectedness of a target Node or querySelector inside a document
ConnectionObserver is a tiny (1kb) API that provides a way to asynchronously observe the connectedness of a target Node or querySelector inside a document.
With ConnectionObserver, you have a low-level building block that can be used to build functionality on top of when you need to
perform work when a Node lives inside the DOM, and/or perform work when it becomes detached.
- Familiar API: Follows the same conventions as
MutationObserver,IntersectionObserver,PerformanceObserver, andResizeObserver - Asynchronous: Entries are batched together as microtasks
- Tiny (1kb)
- Performant
- Description
- Table of Contents
- Install
- Usage
- API reference
- Contributing
- Maintainers
- Backers
- FAQ
- License
$ npm install @wessberg/connection-observer
$ yarn add @wessberg/connection-observer
$ pnpm add @wessberg/connection-observer
If you are familiar with the family of observers such as MutationObserver and IntersectionObserver, you will feel right at home
with ConnectionObserver. Not only is the API very similar, it is also asynchronous and batches together records on the microtask queue.
import {ConnectionObserver} from "@wessberg/connection-observer";
// Hook up a new ConnectionObserver
const observer = new ConnectionObserver(entries => {
// For each entry, print the connection state as well as the target node to the console
for (const {connected, target} of entries) {
console.log("target:", target);
console.log("connected:", connected);
}
});
// Observe 'someElement' for connectedness
observer.observe(someElement);
// Eventually disconnect the observer when you are done observing elements for connectedness
observer.disconnect();The ConnectionObserver constructor creates and returns a new observer which invokes a specified callback when there are new connectedness entries available.
If you don't call provide any Nodes to the observe method on the ConnectionObserver instance, the callback will never be called since no Nodes will be observed for connectedness.
const connectionObserver = new ConnectionObserver(callback);The ConnectionObserver method observe configures the ConnectionObserver callback to begin receiving notifications of changes to the connectedness of the given Node(s).
The callback will be invoked immediately with the connectedness of the observed Node(s).
connectionObserver.observe(target);The ConnectionObserver method observe also accepts a query selector as the first argument, instead of a specific Node. This enables you to subscribe to connectedness events
for any Nodes that matches your querySelector inside of the document, including any Shadow roots. You can use this functionality for performing actions on elements matching your
querySelector as they enter and leave the DOM. For example:
const connectionObserver = new ConnectionObserver(entries => {
for (const {connected, target} of entries) {
if (connected) {
makeImageFancy(target);
}
}
});
connectionObserver.observe(`img[data-fancy]`);The ConnectionObserver method disconnect will stop watching for the connectedness of all observed Nodes such that the callback won't be triggered any longer.
connectionObserver.disconnect();ConnectionObserver is asynchronous which means that ConnectionEntries will be batched together and be provided to the callback given in the constructor (see this section) as a microtask.
The method takeRecords returns the entries that are currently queued in the batch and haven't been processed yet, leaving the connection queue empty. This may be useful if you want to immediately fetch all pending connection records immediately before disconnecting the observer, so that any pending changes can be processed.
const entries = connectionObserver.takeRecords();This section includes a more code-oriented introduction to the types and interfaces of ConnectionObserver
class ConnectionObserver {
[Symbol.toStringTag]: string;
/**
* Constructs a new ConnectionObserver
* @param {ConnectionCallback} callback
*/
constructor(callback: ConnectionCallback);
/**
* Observe the given node or query selector for connections/disconnections.
* If given a Node, that specific Node will be observed. If given a query selector, such
* as for example "img[data-some-attr]", for each new MutationRecord, the query selector
* will be executed and the matched nodes will be observed for connections/disconnections
* @param {string} target
* @example {observe("img[data-some-attr]")}
*/
observe(target: Node | string): void;
/**
* Takes the records immediately (instead of waiting for the next flush)
* @return {ConnectionRecord[]}
*/
takeRecords(): ConnectionRecord[];
/**
* Disconnects the ConnectionObserver such that none of its callbacks will be invoked any longer
*/
disconnect(): void;
}A ConnectionCallback must be provided to the constructor of ConnectionObserver and will be invoked when
there are new ConnectionRecords available.
type ConnectionCallback = (entries: ConnectionRecord[], observer: IConnectionObserver) => void;ConnectionCallbacks are invoked with an array of ConnectionRecords. Those have the following members:
interface ConnectionRecord {
/**
* Whether or not the node is Connected
*/
readonly connected: boolean;
/**
* The target Node
*/
readonly target: Node;
}Do you want to contribute? Awesome! Please follow these recommendations.
 |
|---|
| Frederik Wessberg Twitter: @FredWessberg Github: @wessberg Lead Developer |
 |
 |
|---|---|
| Bubbles Twitter: @use_bubbles |
Christopher Blanchard |
With MutationObserver, we can watch for changes being made to the DOM tree from any root,
but using it to watch for when an arbitrary Node is attached to or detached from the DOM is very hard since that requires tracking all Shadow Roots.
There is an ongoing discussion about adding support for tracking connectedness of any Node via MutationObservers, and this library aims to render itself obsolete if and when that becomes a reality in favor of a polyfill.
MutationEvents are deprecated and I would discourage you from using them. Additionally, these were designed and implemented in browser before Shadow DOM v1 came to be, and they are somewhat unreliable for tracking the connectedness of Nodes inside of Shadow roots. Additionally, they are synchronous which is bad for performance and has proven to be performance-killers in numerous benchmarks and investigations.
MIT © Frederik Wessberg (@FredWessberg) (Website)
