Mutation observers

Many apps and sites build their own custom controls with HTML and JavaScript. These controls are not intrinsic like the ones provided by the input element. To work well with the rest of the web platform, these controls must be able to adapt to content changes, respond to events, and handle user interaction. Apps and sites need to monitor the DOM for mutations and respond accordingly.

In Internet Explorer 11, web developers gain support for W3C DOM4 Mutation observers to help monitor which DOM mutations they need to observe and follow. For example, they might want notification after a script executes, but before a new frame is painted on the screen.

Mutation observers provide a fast-performing replacement for all the same scenarios supported by mutation events, and an alternative to the scenarios supported by property change events. For more info, see "Migrating mutation and property change events to Mutation Observers".

The MutationObserver object

A MutationObserver object is used to monitor and record specified changes on one or more DOM nodes. The types of changes you can observe include:

• Additions and removals of child nodes
• Additions, removals, and changes of attributes
• Changes to child text node values

The MutationObserver constructor requires a callback function that it uses to notify you about mutations:

// Create an observer object and assign a callback function
var observerObject = new MutationObserver(mutationObjectCallback);

Once you create a new MutationObserver object, use the observe method to register it on the node(s) you want to monitor and to specify the types of information to collect:

// Register the target node to observe and specify which DOM changes to watch
observerObject.observe(targetObject, { 
  attributes: true,
  attributeFilter: ["id", "dir"],
  attributeOldValue: true,
  childList: true
});

You can monitor and collect the following types of info:

When a relevant mutation happens, the MutationObserver records the change information you requested in a MutationRecord object and invokes your callback function, but not until all scripts within the current scope have run. It's possible that more than one mutation (each represented by a single MutationRecord) will occur since the last time the callback was invoked:

// Create an observer object and assign a callback function
var observerObject = new MutationObserver(mutationObjectCallback);

// Register the target node to observe and specify which DOM changes to watch
observerObject.observe(targetObject, { 
  attributes: true,
  attributeFilter: ["id", "dir"],
  attributeOldValue: true,
  childList: true
});

// This will invoke the mutationObjectCallback function (but only after all script in this
// scope has run). For now, it simply queues a MutationRecord object with the change information
targetObject.appendChild(document.createElement('div'));

// Now a second MutationRecord object will be added, this time for an attribute change
targetObject.dir = 'rtl';

Your callback function is invoked with two parameters:

• An array of MutationRecord objects representing the changes that occurred on the element (or elements)
• A reference to the MutationObserver object that invoked the callback

The MutationRecord object

You can inspect individual MutationRecord objects to identify the type and content of the change:

// Inspect the array of MutationRecord objects to identify the nature of the change
function mutationObjectCallback(mutationRecordsList) {
  console.log("mutationObjectCallback invoked.");

  mutationRecordsList.forEach(function(mutationRecord) {
    console.log("Type of mutation: " + mutationRecord.type);
    if ("attributes" === mutationRecord.type) {
      console.log("Old attribute value: " + mutationRecord.oldValue);
    }
  });
}

A MutationRecord object provides the following information:

The MutationObserver's array of MutationRecord objects accumulate all relevant changes until the takeRecords method is called, which removes the records in the queue and returns them.

To stop monitoring changes, call the MutationObserver's disconnect method. Be sure to first call the takeRecords method if you need to save your mutation data. It won't be preserved after you disconnect a MutationObserver from its target element(s).

While its possible to reuse a MutationObserver instance after you disconnect it from its previous target element(s), its callback function cannot be modified and target elements / change recording options must be registered again using the observe method.

Related topics

Migrating mutation and property change events to Mutation Observers