MutationObserver
MutationObserver
provides developers 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 thisMutationObserver
instance.
Instance methods
void observe( |
void disconnect(); |
Array takeRecords(); |
observe()
Registers the MutationObserver
instance to receive notifications of DOM mutations on the specified node.
void observe( <a title="A Node is an interface from which a number of DOM types inherit, and allows these various types to be treated (or tested) similarly." href="dom/Node"><code>Node</code></a> target, <a href="dom/mutationobserver#MutationObserverInit"><code>MutationObserverInit</code></a> 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, 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 MutationRecord
s.
MutationObserverInit
MutationObserverInit
is an object which can specify the following properties:
childList
, attributes
, or characterData
must be set to true
. Otherwise, "An invalid or illegal string was specified" error is thrown.Property | Description |
childList |
Set to true if additions and removals of the target node's child elements (including text nodes) are to be observed. |
attributes |
Set to true if mutations to target's attributes are to be observed. |
characterData |
Set to true if mutations to target's data are to be observed. |
subtree |
Set to true if mutations to target and target's descendants are to be observed. |
attributeOldValue |
Set to true if attributes is set to true and target's attribute value before the mutation needs to be recorded. |
characterDataOldValue |
Set to true if characterData is set to true and target's data before the mutation needs to be recorded. |
attributeFilter |
Set to an array of attribute local names (without namespace) if not all attribute mutations need to be observed. |
Example usage
The following example was taken from this blog post.
// 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();
Additional reading
- A brief overview
- A more in-depth discussion
- A screencast by Chromium developer Rafael Weinstein
- The mutation summary library
Specifications
Specification | Status | Comment |
---|---|---|
DOM The definition of 'MutationObserver' in that specification. |
Living Standard | |
DOM4 The definition of 'MutationObserver' in that specification. |
Recommendation |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | 18 -webkit 26 |
14 (14) | 11 | 15 | 6.0 -webkit |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | 4.4 | 18 -webkit 26 |
14.0 (14) | 11 (8.1) | 15 | 6 -webkit 7 |
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/mutationobserver