MutationObserver.MutationObserver()

The DOM MutationObserver() constructor — part of the MutationObserver interface — creates and returns a new observer which invokes a specified callback when DOM events occur. DOM observation does not begin immediately; the observe() method must be called first to establish which portion of the DOM to watch and what kinds of changes to watch for.

Syntax

const observer = new MutationObserver(callback)

Parameters

callback

A function which will be called on each DOM change that qualifies given the observed node or subtree and options.

The callback function takes as input two parameters:

  1. An array of MutationRecord objects, describing each change that occurred; and
  2. the MutationObserver which invoked the callback.

See the example below for more details.

Return value

A new MutationObserver object, configured to call the specified callback when DOM mutations occur.

Example

This example simply creates a new MutationObserver configured to watch a node and all of its children for additions and removals of elements to the tree, as well as any changes to attributes on any of the elements in the tree.

The callback function

function callback(mutationList, observer) {
  mutationList.forEach( (mutation) => {
    switch(mutation.type) {
      case 'childList':
        /* One or more children have been added to and/or removed
           from the tree.
           (See mutation.addedNodes and mutation.removedNodes.) */
        break;
      case 'attributes':
        /* An attribute value changed on the element in
           mutation.target. 
           The attribute name is in mutation.attributeName, and 
           its previous value is in mutation.oldValue. */
        break;
    }
  });
}

The callback() function is invoked when the observer sees changes matching the configuration of the observation request specified when calling observe() to begin watching the DOM.

The kind of change that took place (either a change to the list of children, or a change to an attribute) is detected by looking at the mutation.type property.

Creating and starting the observer

This code actually sets up the observation process.

const targetNode = document.querySelector("#someElement");
const observerOptions = {
  childList: true,
  attributes: true,
  
  // Omit (or set to false) to observe only changes to the parent node
  subtree: true 
}

const observer = new MutationObserver(callback);
observer.observe(targetNode, observerOptions);

The desired subtree is located by finding an element with the ID someElement. A set of options for the observer is also established in the observerOptions record. In it, we specify values of true for both childList and attributes, so we get the information we want.

Then the observer is instantiated, specifying the callback() function. We begin observing the DOM nodes of interest by calling observe(), specifying the target node and the options object.

From this point until disconnect() is called, callback() will be called each time an element is added to or removed from the DOM tree rooted at targetNode, or any of those elements' attributes are changed.

Specifications

Specification Status Comment
DOM
The definition of 'MutationObserver()' in that specification.
Living Standard

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
MutationObserver() constructorChrome Full support 26
Full support 26
No support 18 — 26
Prefixed
Prefixed Implemented with the vendor prefix: WebKit
Edge Full support 12Firefox Full support 14IE Full support 11Opera Full support 15Safari Full support 7
Full support 7
No support 6 — 7
Prefixed
Prefixed Implemented with the vendor prefix: WebKit
WebView Android Full support Yes
Full support Yes
No support ? — ?
Prefixed
Prefixed Implemented with the vendor prefix: WebKit
Chrome Android Full support 26
Full support 26
No support 18 — 26
Prefixed
Prefixed Implemented with the vendor prefix: WebKit
Firefox Android Full support 14Opera Android Full support 14Safari iOS Full support 7
Full support 7
No support 6 — 7
Prefixed
Prefixed Implemented with the vendor prefix: WebKit
Samsung Internet Android Full support 1.5
Full support 1.5
No support 1.0 — 1.5
Prefixed
Prefixed Implemented with the vendor prefix: WebKit

Legend

Full support  
Full support
Requires a vendor prefix or different name for use.
Requires a vendor prefix or different name for use.