Revision Content

{{deprecated_header()}}

Mutation events provide amechanism for a web page or an extension to get notified about changes made to the DOM. Use Mutation Observers instead if possible.

Preface

The mutation events have been marked as deprecated in the DOM Events specification, as the API's design is flawed (see details in the "DOM Mutation Events Replacement: The Story So Far / Existing Points of Consensus" post to public-webapps).

Mutation Observers are the proposed replacement for mutation events in DOM4. They are expected to be included in Firefox 14 and Chrome 18.

The practical reasons to avoid the mutation events are performance issues and cross-browser support.

Performance

Adding DOM mutation listeners to a document profoundly degrades the performance of further DOM modifications to that document (making them 1.5 - 7 times slower!). Moreover, removing the listeners does not reverse the damage.

Usage

The event object is passed to the listener in a {{ domxref("MutationEvent") }} (see its definition in the specification) for most events, and {{ domxref("MutationNameEvent") }} for DOMAttributeNameChanged and DOMElementNameChanged.

Revision Source

<p>{{deprecated_header()}}</p>
<p><strong>Mutation events</strong> provide a<em> </em>mechanism for a web page or an extension to get notified about changes made to the DOM. <span style="background-color:#ffff00;">Use <a href="/en-US/docs/Web/API/MutationObserver" title="/en-US/docs/Web/API/MutationObserver">Mutation Observers</a> instead if possible.</span></p>
<h2 id="Preface">Preface</h2>
<p id="Replacement.3A_mutation_observers">The mutation events have been marked as deprecated in <a class="external" href="http://www.w3.org/TR/DOM-Level-3-Events/#events-mutationevents">the DOM Events specification</a>, as the API's design is flawed (see details in the "DOM Mutation Events Replacement: The Story So Far / Existing Points of Consensus" post to <span id="to"><a class="external" href="http://lists.w3.org/Archives/Public/public-webapps/2011JulSep/0779.html">public-webapps</a>)</span>.</p>
<p><a href="/en-US/docs/Web/API/MutationObserver">Mutation Observers</a> are the proposed replacement for mutation events in DOM4. They are expected to be included in Firefox 14 and <a class="external" href="http://updates.html5rocks.com/2012/02/Detect-DOM-changes-with-Mutation-Observers" title="http://updates.html5rocks.com/2012/02/Detect-DOM-changes-with-Mutation-Observers">Chrome 18</a>.</p>
<p>The practical reasons to avoid the mutation events are <strong>performance issues</strong> and <strong>cross-browser support</strong>.</p>
<h3 id="Performance">Performance</h3>
<p>Adding DOM mutation listeners to a document <a class="external" href="http://groups.google.com/group/mozilla.dev.platform/browse_thread/thread/2f42f1d75bb906fb?pli=1" rel="external" target="_blank" title="http://groups.google.com/group/mozilla.dev.platform/browse_thread/thread/2f42f1d75bb906fb?pli=1">profoundly degrades the performance</a> of further DOM modifications to that document (making them 1.5 - 7 times slower!). Moreover, removing the listeners does not reverse the damage.</p>
<p>The performance effect is <a class="link-https" href="https://groups.google.com/forum/#!topic/mozilla.dev.platform/UH2VqFQRTDA" title="https://groups.google.com/forum/#!topic/mozilla.dev.platform/UH2VqFQRTDA">limited to the documents that have the mutation event listeners</a>.</p>
<h3 id="Cross-browser_support">Cross-browser support</h3>
<p>These events are not implemented consistently across different browsers, for example:</p>
<ul>
<li>IE prior to version 9 didn't support the mutation events at all and does not implement some of them correctly in version 9 (<a class="external" href="http://help.dottoro.com/ljmcxjla.php" title="http://help.dottoro.com/ljmcxjla.php">for example, DOMNodeInserted</a>)</li>
<li>WebKit doesn't support DOMAttrModified (see <a class="link-https" href="https://bugs.webkit.org/show_bug.cgi?id=8191" title="https://bugs.webkit.org/show_bug.cgi?id=8191">webkit bug 8191</a> and <a class="external" href="http://about.silkapp.com/page/Mutation%20Events:%20What%20Happen" title="http://about.silkapp.com/page/Mutation%20Events:%20What%20Happen">the workaround</a>)</li>
<li>"mutation name events", i.e. DOMElementNameChanged and DOMAttributeNameChanged are not supported in Firefox (as of version 11), and probably in other browsers as well.</li>
<li>...</li>
</ul>
<p>Dottoro <a class="external" href="http://help.dottoro.com/ljfvvdnm.php#additionalEvents" title="http://help.dottoro.com/ljfvvdnm.php#additionalEvents">documents browser support for mutation events</a>.</p>
<h2 id="Mutation_events_list">Mutation events list</h2>
<p>The following is a list of all mutation events, as defined in <a class="external" href="http://www.w3.org/TR/DOM-Level-3-Events/#events-mutationevents" title="http://www.w3.org/TR/DOM-Level-3-Events/#events-mutationevents">DOM Level 3 Events specification</a>:</p>
<ul>
<li><code>DOMAttrModified</code></li>
<li><code>DOMAttributeNameChanged</code></li>
<li><code>DOMCharacterDataModified</code></li>
<li><code>DOMElementNameChanged</code></li>
<li><code>DOMNodeInserted</code></li>
<li><code>DOMNodeInsertedIntoDocument</code></li>
<li><code>DOMNodeRemoved</code></li>
<li><code>DOMNodeRemovedFromDocument</code></li>
<li><code>DOMSubtreeModified</code></li>
</ul>
<h2 id="Usage">Usage</h2>
<p>You can register a listener for mutation events using <a href="/en/DOM/element.addEventListener" title="en/DOM/element.addEventListener">element.addEventListener</a> as follows:</p>
<pre>
<code>element.addEventListener("DOMNodeInserted", function (ev) {</code>
// ...
<code>}, false);</code>
</pre>
<p>The event object is passed to the listener in a {{ domxref("MutationEvent") }} (see <a class="external" href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MutationEvent" title="http://www.w3.org/TR/DOM-Level-3-Events/#events-MutationEvent">its definition in the specification</a>) for most events, and {{ domxref("MutationNameEvent") }} for <code>DOMAttributeNameChanged</code> and <code>DOMElementNameChanged</code>.</p>