Neptune: Planet or Myth?

    TypeScript icon, indicating that this package has built-in type declarations

    1.0.5 • Public • Published

    An API that provides a way to asynchronously observe the connectedness of a target Node or querySelector inside a document

    Downloads per month NPM version Dependencies Contributors code style: prettier License: MIT Support on Patreon


    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.


    Table of Contents



    $ 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
    // Eventually disconnect the observer when you are done observing elements for connectedness

    Constructing a ConnectionObserver

    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);

    Observing Nodes for connectedness

    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).


    Observing querySelectors for connectedness

    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) {

    Disconnecting the ConnectionObserver

    The ConnectionObserver method disconnect will stop watching for the connectedness of all observed Nodes such that the callback won't be triggered any longer.


    Taking ConnectionRecords immediately

    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();

    API reference

    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
    Frederik Wessberg
    Twitter: @FredWessberg
    Github: @wessberg
    Lead Developer


    Bubbles Christopher Blanchard
    Twitter: @use_bubbles
    Christopher Blanchard


    Patrons on Patreon


    Why can't you just use MutationObservers for this

    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.

    Why wouldn't you use MutationEvents for this

    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)


    npm i @wessberg/connection-observer

    DownloadsWeekly Downloads






    Unpacked Size

    60.1 kB

    Total Files


    Last publish


    • wessberg