{"id":24229,"date":"2015-07-02T21:01:52","date_gmt":"2015-07-02T13:01:52","guid":{"rendered":"https:\/\/www.hongkiat.com\/blog\/?p=24229"},"modified":"2024-07-30T19:21:16","modified_gmt":"2024-07-30T11:21:16","slug":"mutationobserver-api","status":"publish","type":"post","link":"https:\/\/www.hongkiat.com\/blog\/mutationobserver-api\/","title":{"rendered":"How to Use the MutationObserver API for Tracking DOM Changes"},"content":{"rendered":"

Imagine this scenario: Rita, a magazine writer, is editing an article online. She saves her changes and sees the message \u201cChanges saved!\u201d Just then, she notices a typo she missed. She fixes it and is about to click \u201csave\u201d when she gets an angry phone call from her boss.<\/p>\n

After the call, she turns back to the screen, sees \u201cChanges saved!\u201d shuts down her computer, and storms out of the office.<\/p>\n

Apart from my poor story-telling skills, we can see from this short scenario the trouble that persistent message caused. To avoid this in the future, we should use a message that either prompts the user to acknowledge by clicking it or vanishes on its own<\/strong>. Using the latter for quick messages is a good idea.<\/p>\n

We already know how to make an element disappear from a page, so that shouldn\u2019t be a problem. What we need to know is when it appeared<\/strong>, so we can make it disappear after a reasonable time.<\/p>\n

MutationObserver API<\/h2>\n

When a DOM element (like a message div<\/code>) or any other node changes, we should be able to detect it. For a long time, developers had to rely on hacks and frameworks due to the lack of a native API. But that has changed.<\/p>\n

We now have MutationObserver<\/strong> (previously Mutation Events). MutationObserver<\/code> is a JavaScript native object with a set of properties and methods. It lets us observe changes on any node<\/strong>, such as DOM Element, Document, Text, etc. By mutation, we mean the addition or removal of a node and changes to a node\u2019s attributes and data<\/strong>.<\/p>\n

Let\u2019s see an example for better understanding. We\u2019ll first set up where a message appears upon a button click, like the one Rita saw. Then we\u2019ll create and link a mutation observer to that message box<\/strong> and code the logic to auto-hide the message<\/strong>. Sound good?<\/p>\n

Note<\/strong>: You might be thinking, \u201cWhy not just hide the message from inside the button click event itself in JavaScript?<\/em>\u201d In my example, I\u2019m not working with a server, so of course the client is responsible for showing the message and can hide it easily. But like in Rita\u2019s editing tool, if the server decides to change the DOM content, the client can only stay alert and wait.<\/p>\n

First, we create the setup to show the message on button click.<\/p>\n

\r\n<div id=\"msg\"><\/div><br \/>\r\n<button>Show Message<\/button>\r\n<\/pre>\n
\r\nvar msg = document.querySelector('#msg'),\r\n    SUCCESSMSG = \"Changes Saved!\";\r\n\r\n\/* Add button click event *\/\r\ndocument\r\n    .querySelector('button')\r\n    .addEventListener('click', showMsg);\r\n\r\nfunction showMsg() {\r\n    msg.textContent = SUCCESSMSG;\r\n    msg.style.background = 'teal';\r\n}\r\n<\/pre>\n
Once we have the initial setup running, let\u2019s do the following:<\/p>\n
    \n
  • Create a MutationObserver<\/code> object with a user-defined callback function (the function is defined later in the post). The function will execute on every mutation observed by the MutationObserver<\/code>.<\/li>\n
  • Create a config object to specify the kind of mutations to be observed by the MutationObserver<\/code>.<\/li>\n
  • Bind the MutationObserver<\/code> to the target, which is the \u2018msg\u2019 div<\/code> in our example.<\/li>\n<\/ul>\n
    \r\n(function startObservation() {\r\n    \/\/ 1) Create a MutationObserver object\r\n    var observer = new MutationObserver(function(mutations) { \r\n        mutationObserverCallback(mutations);\r\n    });\r\n    \r\n    \/\/ 2) Create a config object\r\n    var config = {childList: true};\r\n    \r\n    \/\/ 3) Bind observer to the target\r\n    observer.observe(msg, config);\r\n})();\r\n<\/pre>\n
    Below is a list of properties for the config<\/code> object identifying the different kinds of mutations. Since in our example we only deal with a child text node created for the message text, we\u2019ve used the childList<\/code> property.<\/p>\n
    Kinds of Mutations Observed<\/h2>\n\n\n\n\n\n\n
    Property<\/td>\nWhen Set to true<\/code><\/td>\n<\/tr>\n<\/thead>\n
    childList<\/strong><\/td>\nInsertion and removal of the target\u2019s child nodes are observed.<\/td>\n<\/tr>\n
    attributes<\/strong><\/td>\nChanges in the target\u2019s attributes are observed.<\/td>\n<\/tr>\n
    characterData<\/strong><\/td>\nChanges in the target\u2019s data are observed.<\/td>\n<\/tr>\n<\/table>\n
    Now, let\u2019s look at the callback function that gets executed on every observed mutation.<\/p>\n
    \r\nfunction mutationObserverCallback(mutations) {\r\n    \/\/ Grab the first mutation\r\n    var mutationRecord = mutations[0];\r\n\r\n    \/\/ If a child node was added, hide the msg after 2s\r\n    if (mutationRecord.addedNodes[0] !== undefined) {\r\n        setTimeout(hideMsg, 2000);\r\n    }\r\n}\r\n\r\nfunction hideMsg() {\r\n    msg.textContent = '';\r\n    msg.style.background = 'none';\r\n}\r\n<\/pre>\n
    Since we\u2019re only adding a message to the div<\/code>, we\u2019ll just grab the first mutation observed on it and check if a text node was inserted. If we have more than one change happening, we can loop through the mutations<\/code> array.<\/p>\n
    Every mutation in the mutations<\/code> array is represented by the object MutationRecord<\/code> with the following properties:<\/p>\n
    Properties of MutationRecord<\/em><\/h2>\n\n\n\n\n\n\n\n\n\n\n\n\n
    Property<\/td>\nReturns<\/td>\n<\/tr>\n<\/thead>\n
    addedNodes<\/strong><\/td>\nEmpty array or array of nodes added.<\/td>\n<\/tr>\n
    attributeName<\/strong><\/td>\nNull or name of the attribute that was added, removed, or changed.<\/td>\n<\/tr>\n
    attributeNamespace<\/strong><\/td>\nNull or namespace of the attribute that was added, removed, or changed.<\/td>\n<\/tr>\n
    nextSibling<\/strong><\/td>\nNull or next sibling of the node that was added or removed.<\/td>\n<\/tr>\n
    oldValue<\/strong><\/td>\nNull or previous value of the attribute or data changed.<\/td>\n<\/tr>\n
    previousSibling<\/strong><\/td>\nNull or previous sibling of the node that was added or removed.<\/td>\n<\/tr>\n
    removedNodes<\/strong><\/td>\nEmpty array or array of nodes that were removed.<\/td>\n<\/tr>\n
    target<\/strong><\/td>\nNode targeted by the MutationObserver<\/code>.<\/td>\n<\/tr>\n
    type<\/strong><\/td>\nType of mutation observed.<\/td>\n<\/tr>\n<\/table>\n
    And\u2026 that\u2019s it. We just have to put the code together for the final step.<\/p>\n