Revision 1076658 of MutationObserver

<p>{{APIRef("DOM")}}</p>

<p><code>MutationObserver</code> provides developers a way to react to changes in a <a href="/en-US/docs/DOM">DOM</a>. It is designed as a replacement for <a href="/en-US/docs/DOM/Mutation_events">Mutation Events</a> defined in the DOM3 Events specification.</p>

<h2 id="Constructor">Constructor</h2>

<h3 id="MutationObserver()"><code>MutationObserver()</code></h3>

<p>Constructor for instantiating new DOM mutation observers.</p>

<pre class="syntaxbox">
new MutationObserver(
  function callback
);
</pre>

<h6 id="Parameters">Parameters</h6>

<dl>
 <dt><code>callback</code></dt>
 <dd>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 {{domxref("MutationRecord")}}. The second is this <code>MutationObserver</code> instance.</dd>
</dl>

<h2 id="Instance_methods">Instance methods</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <td><code>void <a href="#observe()">observe</a>( {{domxref("Node")}} target, <a href="#MutationObserverInit">MutationObserverInit</a> options );</code></td>
  </tr>
  <tr>
   <td><code>void <a href="#disconnect()">disconnect</a>();</code></td>
  </tr>
  <tr>
   <td><code>Array <a href="#takeRecords()">takeRecords</a>();</code></td>
  </tr>
 </tbody>
</table>

<div class="note">
<p><strong>Note</strong>: {{domxref("Node")}} target should not be confused with <a href="https://nodejs.org/en/">NodeJS</a>.</p>
</div>

<h3 id="observe()"><code>observe()</code></h3>

<p>Registers the <code>MutationObserver</code> instance to receive notifications of DOM mutations on the specified node.</p>

<pre class="syntaxbox">
void observe(
  {{domxref("Node")}} target,
  <a href="#MutationObserverInit"><code>MutationObserverInit</code></a> options
);
</pre>

<h6 id="Parameters_2">Parameters</h6>

<dl>
 <dt><code>target</code></dt>
 <dd>The {{domxref("Node")}} on which to observe DOM mutations.</dd>
 <dt><code>options</code></dt>
 <dd>A <a href="#MutationObserverInit"><code>MutationObserverInit</code></a> object, specifies which DOM mutations should be reported.</dd>
</dl>

<div class="note">NOTE: Adding an observer to an element is just like addEventListener, if you observe the element multiple times it does not make a difference. Meaning if you observe element twice, the observe callback does not fire twice, nor will you have to run disconnect() twice. In other words, once an element is observed, observing it again with the same observer instance will do nothing. However if the callback object is different it will of course add another observer to it.</div>

<h3 id="disconnect()"><code>disconnect()</code></h3>

<p>Stops the <code>MutationObserver</code> instance from receiving notifications of DOM mutations. Until the <a href="#observe()"><code>observe()</code></a> method is used again, observer's callback will not be invoked.</p>

<pre class="syntaxbox">
void disconnect();
</pre>

<h3 id="takeRecords()"><code>takeRecords()</code></h3>

<p>Empties the <code>MutationObserver</code> instance's record queue and returns what was in there.</p>

<pre class="syntaxbox">
Array takeRecords();
</pre>

<h6 id="Return_value">Return value</h6>

<p>Returns an Array of {{domxref("MutationRecord")}}s.</p>

<h2 id="MutationObserverInit"><code>MutationObserverInit</code></h2>

<p><code>MutationObserverInit</code> is an object which can specify the following properties:</p>

<div class="note">NOTE: At the very least, <code>childList</code>, <code>attributes</code>, or <code>characterData</code> must be set to <code>true</code>. Otherwise, "An invalid or illegal string was specified" error is thrown.</div>

<table class="standard-table">
 <tbody>
  <tr>
   <td class="header">Property</td>
   <td class="header">Description</td>
  </tr>
  <tr>
   <td><code>childList</code></td>
   <td>Set to <code>true</code> if additions and removals of the target node's child elements (including text nodes) are to be observed.</td>
  </tr>
  <tr>
   <td><code>attributes</code></td>
   <td>Set to <code>true</code> if mutations to target's attributes are to be observed.</td>
  </tr>
  <tr>
   <td><code>characterData</code></td>
   <td>Set to <code>true</code> if mutations to target's data are to be observed.</td>
  </tr>
  <tr>
   <td><code>subtree</code></td>
   <td>Set to <code>true</code> if mutations to target and target's descendants are to be observed.</td>
  </tr>
  <tr>
   <td><code>attributeOldValue</code></td>
   <td>Set to <code>true</code> if <code>attributes</code> is set to <code>true</code> and target's attribute value before the mutation needs to be recorded.</td>
  </tr>
  <tr>
   <td><code>characterDataOldValue</code></td>
   <td>Set to <code>true</code> if <code>characterData</code> is set to <code>true</code> and target's data before the mutation needs to be recorded.</td>
  </tr>
  <tr>
   <td><code>attributeFilter</code></td>
   <td>Set to an array of attribute local names (without namespace) if not all attribute mutations need to be observed.</td>
  </tr>
 </tbody>
</table>

<h2 id="Example_usage">Example usage</h2>

<p>The following example was taken from <a class="external" href="https://hacks.mozilla.org/2012/05/dom-mutationobserver-reacting-to-dom-changes-without-killing-browser-performance/" rel="freelink">this blog post</a>.</p>

<pre class="brush: js">
// select the target node
var target = document.getElementById('some-id');
 
// create an observer instance
var observer = new MutationObserver(function(mutations) {
  mutations.forEach(function(mutation) {
    console.log(mutation.type);
  });    
});
 
// configuration of the observer:
var config = { attributes: true, childList: true, characterData: true };
 
// pass in the target node, as well as the observer options
observer.observe(target, config);
 
// later, you can stop observing
observer.disconnect();
</pre>

<h2 id="Additional_reading">Additional reading</h2>

<ul>
 <li><a class="external" href="https://updates.html5rocks.com/2012/02/Detect-DOM-changes-with-Mutation-Observers" rel="freelink">A brief overview</a></li>
 <li><a class="external" href="https://hacks.mozilla.org/2012/05/dom-mutationobserver-reacting-to-dom-changes-without-killing-browser-performance/" rel="freelink">A more in-depth discussion</a></li>
 <li><a class="external" href="https://www.youtube.com/watch?v=eRZ4pO0gVWw" rel="freelink">A screencast by Chromium developer Rafael Weinstein</a></li>
 <li><a class="external" href="https://code.google.com/p/mutation-summary/" rel="freelink">The mutation summary library</a></li>
</ul>

<h2 id="Specifications" name="Specifications">Specifications</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('DOM WHATWG', '#mutationobserver', 'MutationObserver')}}</td>
   <td>{{ Spec2('DOM WHATWG') }}</td>
   <td>&nbsp;</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM4', '#mutationobserver', 'MutationObserver')}}</td>
   <td>{{ Spec2('DOM4') }}</td>
   <td>&nbsp;</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{CompatibilityTable}}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>18 {{property_prefix("-webkit")}}<br />
    26</td>
   <td>{{CompatGeckoDesktop(14)}}</td>
   <td>11</td>
   <td>15</td>
   <td>6.0 {{property_prefix("-webkit")}}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Chrome for Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Phone</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>4.4</td>
   <td>18 {{property_prefix("-webkit")}}<br />
    26</td>
   <td>{{CompatGeckoMobile(14)}}</td>
   <td>11 (8.1)</td>
   <td>15</td>
   <td>6 {{property_prefix("-webkit")}}<br />
    7</td>
  </tr>
 </tbody>
</table>
</div>