Mutation Observer
<wa-mutation-observer>
Mutation observers watch for changes to an element's DOM tree and emit an event when they occur. Provides a thin, declarative interface to the browser's MutationObserver API.
The mutation observer will report changes to the content it wraps through the wa-mutation event. When emitted, a collection of MutationRecord objects will be attached to event.detail that contains information about how it changed.
👆 Click the button and watch the console
<div class="mutation-overview"> <wa-mutation-observer attr="variant"> <wa-button appearance="filled" variant="brand">Click to mutate</wa-button> </wa-mutation-observer> <br /> 👆 Click the button and watch the console <script> const container = document.querySelector('.mutation-overview'); const mutationObserver = container.querySelector('wa-mutation-observer'); const button = container.querySelector('wa-button'); const variants = ['brand', 'success', 'neutral', 'warning', 'danger']; let clicks = 0; // Change the button's variant attribute button.addEventListener('click', () => { clicks++; button.setAttribute('variant', variants[clicks % variants.length]); }); // Log mutations mutationObserver.addEventListener('wa-mutation', event => { console.log(event.detail); }); </script> <style> .mutation-overview wa-button { margin-bottom: 1rem; } </style> </div>
When you create a mutation observer, you must indicate what changes it should respond to by including at least one of attr, child-list, or char-data. If you don't specify at least one of these attributes, no mutation events will be emitted.
Examples
Child List
Use the child-list attribute to watch for new child elements that are added or removed.
<div class="mutation-child-list"> <wa-mutation-observer child-list> <div class="buttons"> <wa-button appearance="filled" variant="brand">Add button</wa-button> </div> </wa-mutation-observer> 👆 Add and remove buttons and watch the console <script> const container = document.querySelector('.mutation-child-list'); const mutationObserver = container.querySelector('wa-mutation-observer'); const buttons = container.querySelector('.buttons'); const button = container.querySelector('wa-button[variant="brand"]'); let i = 0; // Add a button button.addEventListener('click', () => { const button = document.createElement('wa-button'); button.textContent = ++i; buttons.append(button); }); // Remove a button buttons.addEventListener('click', event => { const target = event.target.closest('wa-button:not([variant="brand"])'); event.stopPropagation(); if (target) { target.remove(); } }); // Log mutations mutationObserver.addEventListener('wa-mutation', event => { console.log(event.detail); }); </script> <style> .mutation-child-list .buttons { display: flex; gap: 0.25rem; flex-wrap: wrap; margin-bottom: 1rem; } </style> </div>
Importing
If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.
Import this component directly from the CDN:
import 'https://ka-f.webawesome.com/[email protected]/components/mutation-observer/mutation-observer.js';
After installing Web Awesome via npm, import this component:
import '@awesome.me/webawesome/dist/components/mutation-observer/mutation-observer.js';
If you're self-hosting Web Awesome, import this component from your server:
import './webawesome/dist/components/mutation-observer/mutation-observer.js';
To import this component for React 18 or below, use the following code:
import WaMutationObserver from '@awesome.me/webawesome/dist/react/mutation-observer/index.js';
Slots
Learn more about using slots.
| Name | Description |
|---|---|
| (default) | The content to watch for mutations. |
Attributes & Properties
Learn more about attributes and properties.
| Name | Description | Reflects | |
|---|---|---|---|
attrattr |
Watches for changes to attributes. To watch only specific attributes, separate them by a space, e.g.
attr="class id title". To watch all attributes, use *.Type
string |
|
|
attrOldValueattr-old-value |
Indicates whether or not the attribute's previous value should be recorded when monitoring changes.
Type
booleanDefault
false |
|
|
charDatachar-data |
Watches for changes to the character data contained within the node.
Type
booleanDefault
false |
|
|
charDataOldValuechar-data-old-value |
Indicates whether or not the previous value of the node's text should be recorded.
Type
booleanDefault
false |
|
|
childListchild-list |
Watches for the addition or removal of new child nodes.
Type
booleanDefault
false |
|
|
css |
One or more CSSResultGroup to include in the component's shadow root. Host styles are automatically prepended.
Type
CSSResultGroup | undefinedDefault
styles |
||
disableddisabled |
Disables the observer.
Type
booleanDefault
false |
|
Events
Learn more about events.
| Name | Description |
|---|---|
wa-mutation |
Emitted when a mutation occurs. |