Mutation Observer

<wa-mutation-observer>

Stable

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 to mutate
  
  👆 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

Link to This Section

Child List

Link to This Section

Use the child-list attribute to watch for new child elements that are added or removed.

  
      Add button
    
  👆 Add and remove buttons and watch the console

<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

Link to This Section

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.

CDN

npm

Self-Hosted

React

Import this component directly from the CDN:

import 'https://ka-f.webawesome.com/webawesome@0.17.0/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

Link to This Section

Learn more about using slots.

Name	Description
(default)	The content to watch for mutations.

Attributes & Properties

Link to This Section

Learn more about attributes and properties.

Name	Description	Reflects
`attr` `attr`	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`
`attrOldValue` `attr-old-value`	Indicates whether or not the attribute's previous value should be recorded when monitoring changes. Type `boolean` Default `false`
`charData` `char-data`	Watches for changes to the character data contained within the node. Type `boolean` Default `false`
`charDataOldValue` `char-data-old-value`	Indicates whether or not the previous value of the node's text should be recorded. Type `boolean` Default `false`
`childList` `child-list`	Watches for the addition or removal of new child nodes. Type `boolean` Default `false`
`disabled` `disabled`	Disables the observer. Type `boolean` Default `false`

Events

Link to This Section

Learn more about events.

Name	Description
`wa-mutation`	Emitted when a mutation occurs.

Need a hand?

Report a bug

Ask for help

Mutation Observer

Examples

Child List

Importing

Slots

Attributes & Properties

Events

Quick Links

Recent Searches