An abstraction for Mutation Observer with some extra features
npm install dom-observer[![Build]](https://circleci.com/gh/jstoolkit/dom-observer/tree/master)
[![TestCoverage]](https://codeclimate.com/github/jstoolkit/dom-observer/coverage)
[![SemVer]](http://semver.org/)
[![License]](LICENSE)
An abstraction for Mutation Observer with some extra features in ~1kb gzipped.
Useful to observe an DOM element for changes without taking too much hit on performance, the Mutation Observer technique is used by many libraries and frameworks.
This lib intention is to provide quick and simple access to the Mutation Observer features by abstracting the API into a simple function call and adding some handy methods.
As usual most package managers are supported.
npm install dom-observer
bower install dom-observer
1. Download ZIP
2. Unzip
3. Grab the JS in the dist folder.
4. Profit!
It's really simple if you know how Mutation Observers work.
This lib is designed to ease your life when dealing with MOs.
Take a look at this:
``javascript
// My function that handle mutations
function handleMutations(mutations) {
mutations.forEach(mutation, () => {
console.log('YO', mutation);
});
}
// Import the module, a global var is exposed too if you're not into modules
import observe from 'dom-observer';
const myTarget = document.body;
const myObserver = observe(myTarget, handleMutations);
`
That would be the same as doing the following using just the MutationObserver:
`javascript
// My function that handle mutations
function handleMutations(mutations) {
mutations.forEach(mutation, () => {
console.log('YO', mutation);
});
}
const myTarget = document.body;
const myObserver = new MutationObserver(handleMutations);
myObserver.observe(myTarget, {
attributes: true,
childList: true,
characterData: true
});
`
Notice that with the lib we default to all 3 properties (attributes, childList and characterData) true when you pass no object.
Of course you can specify to just observe attributes by setting it explicitly to true, then the lib will respect that.
In fact, the observe function second argument is MutationObserverInit object. Meaning it will respect options like subtree or attributeFilter too. Please check the MO docs if you're lost.
As you would expect the callback, in this case the handleMutations function, receives as first argument an array of MutationRecord so you can handle the DOM mutations as you please.
You can pass any option already specified in the MutationObserverInit object and two other special properties that you can use:
#### onlyFirstChange
It tells the observer to only send the first change to the callback and then unregister the observer.
Example:
`javascript
// Importing ES module
import observe from 'dom-observer';
// Getting my target
const target = document.body;
// Registering the handler
const mutationHandler = (mutations) => mutations.forEach(mutation, () => console.log(mutation));
// Making my observer getting only the first mutation/change
const myObserver = observe(target, mutationHandler, { onlyFirstChange: true });
// Will trigger mutation = first mutation will be reported to the handler
document.body.appendChild(document.createElement('div'));
// Trigger a second mutation, will not be reported because the myObserver already unregistered
document.body.appendChild(document.createElement('div'));
`
#### onlyLastChange
Sometimes more than one mutation is filed in a render cycle, so you can get just the last one by setting this property.
Example:
`javascript
// Importing ES module
import observe from 'dom-observer';
// Getting my target
const target = document.body;
// Registering the handler
const mutationHandler = (mutations) => mutations.forEach(mutation, () => console.log(mutation));
// Making my observer getting only the first mutation/change
const myObserver = observe(target, mutationHandler, { onlyLastChange: true });
// If the browser batches the mutations this mutation will not be reported
document.body.appendChild(document.createElement('div'));
// This mutation will be reported
document.body.appendChild(document.createElement('div'));
`
It's not recommended but you can add a new target to an existent observer with addTarget.
The lib allows you to add a new target while maintaining the config from the constructor.
`javascript`
myObserver.addTarget(document.querySelector('#myElement'));
If you want to add an entirely new target with config you can do it too with andObserve.
`javascript`
myObserver.andObserve(document.querySelector('#myElement'), {
attributes: true
});
You can change the callback you set on the observe function later on with changeCallback.
`javascript`
function myNewFunc(mutations) {
console.log('I\'m handling the changes now!');
}
myObserver.changeCallback(myNewFunc);
This mirrors the behaviors of the original Mutation Observer takeRecords() method. It works as you expect.
`javascript`
myObserver.takeRecords(); // Will return the records cached
This new handy function wiped the records cache and returns a chainable instance of dom-observer.
`javascript`
myObserver.wipe(); // Cache is now clean and returns myObserver
The lib was designed to make it easy to chain functionality.
`javascript`
const myObserver = observe(myTarget, handleMutations)
.addTarget(document.querySelector('#otherElement'))
.andObserve(document.querySelector('#yetAnotherElement'), {
childList: true
});
While developing the npm run docs script updates the local docs in the docs` folder.
[Build]: https://img.shields.io/circleci/project/jstoolkit/dom-observer/master.svg
[TestCoverage]: https://codeclimate.com/github/jstoolkit/dom-observer/badges/coverage.svg
[SemVer]: https://img.shields.io/:semver-%E2%9C%93-brightgreen.svg
[License]: https://img.shields.io/github/license/jstoolkit/dom-observer.svg