# element-notifier

> A MutationObserver dis/connected helper

Latest version **2.0.3** (published 2026-04-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install element-notifier
pnpm add element-notifier
yarn add element-notifier
bun add element-notifier
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.3 |
| Published | 2026-04-27 |
| First published | 2021-04-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 6.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Andrea Giammarchi |
| Maintainers | webreflection |
| Keywords | mutation, observer, element |

## Links

- npm: https://www.npmjs.com/package/element-notifier
- Repository: https://github.com/WebReflection/element-notifier
- Homepage: https://github.com/WebReflection/element-notifier#readme
- Issues: https://github.com/WebReflection/element-notifier/issues
- npm.io page: https://npm.io/package/element-notifier

## Recent versions

- 2.0.3 (latest) — 2026-04-27
- 2.0.2 — 2026-04-27
- 2.0.1 — 2026-04-27
- 2.0.0 — 2026-04-23
- 1.1.2 — 2022-07-26
- 1.1.1 — 2022-05-23
- 1.1.0 — 2022-05-23
- 1.0.0 — 2022-05-21
- 0.2.0 — 2021-04-20
- 0.1.2 — 2021-04-13
- 0.1.1 — 2021-04-13
- 0.0.0 — 2021-04-13

## README

# element-notifier

A MutationObserver dis/connected helper.

```js
import { notify } from 'element-notifier';

const observer = notify(
  // callback that receives any connected/disconnected element
  (element, connected) => {
    if (connected)
      console.log(element, 'has been connected');
    else
      console.log(element, 'has been disconnected');
  },

  // optional arguments
  document,         // the root element to observe
  MutationObserver  // a MutationObserver (non DOM envs)
);
```

The `observer` is a regular *MutationObserver* instance with a self bound, and instrumented, `.observe(node)` method to observe mutations within fragments too (example: *shadowRoot* nodes).


### Why?

The *MutationObserver* dance with records is easily error prone:

  * records are triggered lazily in a bizarre order
  * records are related to single containers, but inner elements are not notified
  * it's difficult to ensure that within a *MutationObserver* callback, all elements, in the right order of events, get passed along uniquely per event

This helper does just this: it passes to the callback every element that has been added, or removed, from the document.


### About ShadowDOM

While the observer could crawl nodes within a `shadowRoot`, in case it's opened, if nodes are removed from it nothing is notified due *MutationObserver* limitations.

If observing nodes appended or removed from any `shadowRoot` is desired, use [shadow-observer](https://github.com/WebReflection/shadow-observer#readme):

```javascript
import { ShadowObserver, OPEN, CLOSED } from 'shadow-observer';
import { notify } from 'element-notifier';

// augmented method with right options included
const { observe } = notify(
  (node, connected) => { ... },
  document,
  ShadowObserver,
);
```

---
_Source: https://npm.io/package/element-notifier · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._