A "better" implementation of the native MutationObserver
web interface.
This project is a hobby project to support other hobby projects I work on. Development of this package is ongoing; expect frequent breaking changes.
You should not depend on this package for any semi-serious projects.
- Write some tests
- Figure out how to handle Live NodeLists.
The design of the native MutationObserver
interface separates the definition of the observer callback()
function, which is provided as the sole argument when creating a new MutationObserver
instance, from the definition of the target node and observer options, which define what DOM mutations are reported and are provided as arguments when calling the observe()
method of the observer.
This separation of the callback, target node, and observer options arguments is unnecessary and makes reading the through code that implements the MutationObserver
interface confusing. In almost all cases, the target node and observer options could be defined alongside the observe callback when the observer is instantiated. Doing so allows the code for creating mutation observers to be written in a more logical order.
Furthermore, in cases where it is necessary to observe multiple nodes, the MutationObserver
constructor could be adapted to accept a node array or NodeList
in order to observe multiple nodes with a single observer.
This library adds a BetterMutationObserver
interface that extends the native MutationObserver
interface and implements the design improvements described above.
Install the library with NPM or Yarn.
NPM:
npm install better-mutation-observer
Yarn:
yarn better-mutation-observer
Import the library to your project using CommonJS or ES Modules syntax.
CommonJS
const BetterMutationObserver = require('better-mutation-observer')
ES Modules
import { BetterMutationObserver } from 'better-mutation-observer'
The BetterMutationObserver
interface is largely the same as the native MutationObserver
interface with key changes to the required arguments for the observer constructor and the observe()
method on the instance.
This reference documentation is adapted from the MDN docs for the native MutationObserver
interface.
BetterMutationObserver()
– Creates and returns a new BetterMutationObserver
instance, which will invoke a specified callback function when DOM changes occur on the specified node(s).
new BetterMutationObserver(target, options, callback)
target
– A DOMNode
,Node
array, orNodeList
within the DOM tree to watch for changes, or to be the root of a subtree of nodes to be watched.options
– An object providing options that describe which DOM mutations should be reported to thecallback
function. Implements the same options parameters as the nativeMutationObserver
interface. See MDN docs.- Note: In contrast to the native
MutationObserver
interface, the options object is not optional when instantiating the observer.
- Note: In contrast to the native
callback
– A function which will be called on each DOM change that qualifies given the observed node or subtree and options. Implements the same parameters as the nativeMutationObserver
interface. See MDN docs.
observe()
– Initiates the observer instance to begin receiving notifications through its callback function when DOM changes matching the given target and options occur. Unlike the nativeMutationObserver
interface, this version of theobserve()
method accepts no arguments.disconnect()
– Stops the observer instance from receiving further notifications until and unlessobserve()
is called again. Implements the same functionality as the nativeMutationObserver
interface. See MDN docs.takeRecords()
– Removes all pending notifications from the observer's notification queue and returns them in a new array ofMutationRecord
objects. Implements the same functionality as the nativeMutationObserver
interface. See MDN docs.
The following example was adapted from the example provided in the MDN docs for the native MutationObserver
interface.
// Import the `BetterMutationObserver` class
import { BetterMutationObserver } from 'better-mutation-observer'
// Select the node that will be observed for mutations
const targetNode = document.getElementById('some-id');
// Options for the observer (which mutations to observe)
const config = { attributes: true, childList: true, subtree: true };
// Callback function to execute when mutations are observed
const callback = (mutationList, observer) => {
for (const mutation of mutationList) {
if (mutation.type === 'childList') {
console.log('A child node has been added or removed.');
} else if (mutation.type === 'attributes') {
console.log(`The ${mutation.attributeName} attribute was modified.`);
}
}
};
// Create an observer instance linked to the target node(s), configured mutations, and callback function
const observer = new BetterMutationObserver(targetNode, config, callback);
// Start observing the target node(s)
observer.observe();
// Later, you can stop observing
observer.disconnect();
This project uses the MIT License for open source software. See LICENSE.