MutationObserver
lastmod 2025-03-28created 2025-03-282 edits
The MutationObserver interface provides the ability to watch for changes to the DOM tree. It replaces Mutation Events, which were part of the DOM3 Events specification.
Instance methods
disconnect()
Stops the MutationObserver instance from receiving further notifications until observe() is called again.
observe(target, options)
Configures the MutationObserver instance to receive notifications through its callback when DOM changes matching the given options occur.
- target
- A Node (including Element) within the DOM tree to watch for changes, or the root of a subtree of nodes to be watched.
- options
- An object describing which DOM changes to watch. Only DOM changes that satisfy these options are delivered to the MutationObserver's callback.
- At least one of childList, attributes, and characterData must be true; if all three properties are false, a TypeError is thrown.
The available options are as follows.
-
subtree- If set to true, watches the entire subtree rooted at target. The other options are also applied to every node in this subtree rather than only the target node. The default value is false. -
childList- If set to true, detects children being added to or existing children being removed from the target node. If subtree is true, child changes of descendants are detected as well. The default value is false. -
attributes- If set to true, detects attribute changes on the watched node or nodes. The default value is true if attributeFilter or attributeOldValue is specified, otherwise false. -
attributeFilter- An array of attribute names to watch for changes. If this property is not specified, changes to all attributes generate notifications. -
attributeOldValue- If set to true, records the attribute's previous value when an attribute change on a node is detected. The default value is false. -
characterData- If set to true, detects changes to the text within the target node. If subtree is true, text changes of descendants are detected as well. The default value is true if characterDataOldValue is specified, otherwise false. -
characterDataOldValue- If set to true, records the previous text when a text change on a node is detected. The default value is false.
takeRecords()
Empties the MutationObserver's notification queue and returns the notifications that were pending in the queue as a new Array of MutationRecord objects.
Example
// 변경을 감지할 노드 선택
const targetNode = document.getElementById("some-id");
// 감지 옵션 (감지할 변경)
const config = { attributes: true, childList: true, subtree: true };
// 변경 감지 시 실행할 콜백 함수
const callback = (mutationList, observer) => {
for (const mutation of mutationList) {
if (mutation.type === "childList") {
console.log("자식 노드가 추가되거나 제거됐습니다.");
} else if (mutation.type === "attributes") {
console.log(`${mutation.attributeName} 특성이 변경됐습니다.`);
}
}
};
// 콜백 함수에 연결된 감지기 인스턴스 생성
const observer = new MutationObserver(callback);
// 설정한 변경의 감지 시작
observer.observe(targetNode, config);
// 이후 감지 중단 가능
observer.disconnect();