@jackcarey/mutative
v1.3.1
Published
A function for handling global DOM mutation observation
Downloads
3
Maintainers
Readme
mutative
Persistent DOM mutation observations based on CSS query selectors. It's essentially a wrapper for a global MutationObserver that filters records to specific callbacks. The API is similar to MutationObserver, but not the same.
The advantage is that observers can be set up independently/ahead of matching DOM elements, which is useful when working with SPAs or other reactive content.
~1.3kb minified, ~800 bytes gzipped.
Use
Import the package by using a CDN or saving it locally.
// esm.sh
import mutative from "https://esm.sh/@jackcarey/mutative";
// jsdelivr (with ESM)
import mutative from "https://cdn.jsdelivr.net/npm/@jackcarey/mutative/+esm";
//jsDelivr (with version)
import mutative from "https://cdn.jsdelivr.net/npm/@jackcarey/[email protected]/mutative.min.js";
//GitHub (always latest code, possibly unstable)
import mutative from "https://cdn.jsdelivr.net/gh/jackcarey/mutative/mutative.min.js";
// local file
import mutative from "./mutative.min.js";
Then call it in a script tag:
<script type="module">
import mutative from "https://esm.sh/@jackcarey/mutative"
// pass a single selector and callback
Mutative.observe("p",(record)=>console.log(record));
//pass multiple selectors with the same callback
Mutative.observe(["p",".text","*[data-text]"],(record)=>console.log("text mutated",record));
//pass multiple selectors at once with different callbacks
Mutative.observe({
"*[data-text]": (rec)=>console.log(rec),
"p":(rec)=>alert("paragraph edited"),
"output":(rec)=>console.log("calculation updated",rec)
});
//Remove observations for the 'p' selector only
Mutative.disconnect("p");
// Pause all observations
Mutative.disconnect();
//Resume existing observations
Mutative.observe();
</script>
observe()
The parameters are different from the MutationObserver implementation. Instead of a target
and options
there is selectors
and callback
.
selectors
- Several types are allowed:null
- If no arguments are passed, observation of existing selectors will continue.string
- a single CSS query selector.string[]
- multiple CSS query selectors that use the samecallback
.object
- CSS query selectors strings as keys, callbacks as values.
callback
- Only required whenselectors
is a string or array of strings. A function that accepts a MutationRecord as it's only parameter.
disconnect()
Mutations that have been detected but not yet reported to observers are not discarded. Observer callbacks are triggered before disconnection. This method pauses observation and callbacks.
- When called with no arguments: acts the same as disconnect(), ignoring all future observations. Note: this does not clear the internal selector list, so calling
observe()
again will continue with existing selectors. - When passed with an argument: The arguments follow the same formats as
observe()
'sselectors
parameter. Only observers with the passed selectors are removed.
takeRecords()
Takes all records from the Mutative object, use carefully. See: takeRecords().
How it works
A single MutationObserver is created on the document body
with the first call of mutative.observe()
. MutatioNrecords are only passed to callbacks that have a matching selector for at least one of target
, addedNodes
, or removedNodes
.