MutationObserver

MutationObserver provides developers with a way to react to changes in a DOM. It is designed as a replacement for Mutation Events defined in the DOM3 Events specification.

Constructor

MutationObserver()

Constructor for instantiating new DOM mutation observers.

new MutationObserver(
  function callback
);

Parameters

callback

The function which will be called on each DOM mutation. The observer will call this function with two arguments. The first is an array of objects, each of type MutationRecord. The second is this MutationObserver instance.

Instance methods

observe()

Registers the MutationObserver instance to receive notifications of DOM mutations on the specified node.

void observe(
  Node target,
  MutationObserverInit options
);

Parameters

target

The Node on which to observe DOM mutations.

options

A MutationObserverInit object, specifies which DOM mutations should be reported.

disconnect()

Stops the MutationObserver instance from receiving notifications of DOM mutations. Until the observe() method is used again, the observer's callback will not be invoked.

void disconnect();

takeRecords()

Empties the MutationObserver instance's record queue and returns what was in there.

Array takeRecords();

Return value

Returns an Array of MutationRecords.

MutationObserverInit

MutationObserverInit is an object which can specify the following properties:

Example usage

The following example was adapted from this blog post.

// Select the node that will be observed for mutations
var targetNode = document.getElementById('some-id');

// Options for the observer (which mutations to observe)
var config = { attributes: true, childList: true };

// Callback function to execute when mutations are observed
var callback = function(mutationsList) {
    for(var mutation of mutationsList) {
        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 callback function
var observer = new MutationObserver(callback);

// Start observing the target node for configured mutations
observer.observe(targetNode, config);

// Later, you can stop observing
observer.disconnect();

Additional reading

• A brief overview
• A more in-depth discussion
• A screencast by Chromium developer Rafael Weinstein
• The mutation summary library

Specifications

Browser compatibility