https://github.com/untemps/dom-observer
Class to observe when a specific element is added to or removed from the DOM
https://github.com/untemps/dom-observer
dom-elements dom-mutations dom-observer mutationobserver mutations-observer
Last synced: about 1 month ago
JSON representation
Class to observe when a specific element is added to or removed from the DOM
- Host: GitHub
- URL: https://github.com/untemps/dom-observer
- Owner: untemps
- License: mit
- Created: 2021-02-13T15:26:25.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2026-04-28T17:27:23.000Z (about 1 month ago)
- Last Synced: 2026-04-28T18:33:30.019Z (about 1 month ago)
- Topics: dom-elements, dom-mutations, dom-observer, mutationobserver, mutations-observer
- Language: TypeScript
- Homepage:
- Size: 394 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# @untemps/dom-observer
Class to observe DOM mutations of a specific element in one-shot or continuous mode.
The class is a wrapper around the MutationObserver API to target an element in particular.
That means you can observe an element to be added to the DOM and access to its properties, an attribute from that element to be changed and get the old and the new values, the element to be removed from the DOM and destroy all its dependencies.
[](https://github.com/untemps/dom-observer/actions)
## Installation
```bash
yarn add @untemps/dom-observer
```
## Usage
Import `DOMObserver`:
```javascript
import { DOMObserver } from '@untemps/dom-observer'
```
Create an instance of `DOMObserver`:
```javascript
const observer = new DOMObserver()
```
### Watch for recurring mutations
Use the `watch` method when you want to be notified **every time** a mutation occurs — for instance, tracking all successive attribute changes on an element or reacting to every matching node added to the DOM.
```javascript
import { DOMObserver } from '@untemps/dom-observer'
// Track every attribute change on an element
const observer = new DOMObserver()
observer.watch('#foo', (node, event, { attributeName, oldValue } = {}) => {
console.log(`${attributeName} changed from ${oldValue} to ${node.getAttribute(attributeName)}`)
}, { events: [DOMObserver.CHANGE] })
// React to every matching node added or removed
const listObserver = new DOMObserver()
listObserver.watch('.list-item', (node, event) => {
if (event === DOMObserver.ADD) console.log(`Item added: ${node.textContent}`)
if (event === DOMObserver.REMOVE) console.log(`Item removed: ${node.textContent}`)
}, { events: [DOMObserver.ADD, DOMObserver.REMOVE] })
```
Unlike `wait`, `watch` does not return a Promise. It returns `this`, allowing method chaining. Call `clear()` to stop the observation.
Pass `once: true` to stop the observation automatically after the first matching event, without needing to call `clear()` manually:
```javascript
observer.watch('#foo', (node, event) => {
doSomething(node) // called exactly once
}, { events: [DOMObserver.ADD], once: true })
```
Pass `debounce` to delay the callback until mutations have stopped for a given number of milliseconds — useful when you only care about the final state after a burst of rapid changes:
```javascript
observer.watch('#progress', (node) => {
console.log('final value:', node.getAttribute('data-value'))
}, {
events: [DOMObserver.CHANGE],
attributeFilter: ['data-value'],
debounce: 100,
})
```
Pass a `timeout` to automatically stop the observation if no matching mutation occurs within the allotted time:
```javascript
const observer = new DOMObserver()
observer.watch('#foo', (node, event) => {
console.log(`Event: ${event}`)
}, {
events: [DOMObserver.ADD],
timeout: 3000,
onError: (err) => console.error(err.message),
})
```
#### `watch` method arguments
| Props | Type | Description |
| ------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `target` | Element or String | DOM element or selector of the DOM element to observe. See [querySelector spec](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector) |
| `onEvent` | Function | Callback triggered each time an event occurs on the observed element |
| `options` | Object | Options object: |
| - `events` | Array | List of [events](#events) to observe (All events are observed by default) |
| - `attributeFilter` | Array | List of attribute names to observe (DOMObserver.CHANGE event only) |
| - `timeout` | Number | Duration (in ms) after which observation stops if no matching mutation occurred. Triggers `onError` when elapsed. Must be `0` or a positive finite number — throws `[TIMEOUT]` otherwise. |
| - `onError` | Function | Callback triggered when `timeout` elapses with no matching mutation |
| - `signal` | AbortSignal | An `AbortSignal` to stop the observation. If already aborted, `watch()` returns immediately without observing. |
| - `once` | Boolean | When `true`, automatically calls `clear()` after the first matching event. Defaults to `false`. |
| - `debounce` | Number | Milliseconds to wait after the last mutation before invoking the callback. The callback receives the last mutation's arguments. `0` disables debouncing. |
| - `root` | Element or String | DOM element or CSS selector to use as the observation root. Only mutations within this subtree are observed. Defaults to `document.documentElement`. |
| - `filter` | Function | `(node, event, options?) => boolean`. Called before invoking the callback. Return `false` to skip the event and keep observing. |
#### `onEvent` callback arguments
| Props | Type | Description |
| ----------------- | -------------- | --------------------------------------------------------------------------- |
| `node` | Element | Observed element node |
| `event` | String | Event that triggered the callback |
| `options` | Object | Present only for `CHANGE` events: |
| - `attributeName` | String | Name of the attribute that changed |
| - `oldValue` | String or null | Value of the attribute before the mutation |
#### `onError` callback arguments
| Props | Type | Description |
| ------- | ----- | ------------ |
| `error` | Error | Error thrown |
### Wait for a one-shot mutation
Use the `wait` method to get a Promise that resolves on the **first** matching mutation.
```javascript
import { DOMObserver } from '@untemps/dom-observer'
const observer = new DOMObserver()
const { node, event, options: { attributeName } = {} } = await observer.wait('#foo', { events: [DOMObserver.REMOVE, DOMObserver.CHANGE] })
switch (event) {
case DOMObserver.REMOVE: {
console.log('Element ' + node.id + ' has been removed')
break
}
case DOMObserver.CHANGE: {
console.log('Element ' + node.id + ' has been changed (' + attributeName + ')')
break
}
}
```
Pass an **array of targets** to resolve as soon as any one of them fires a matching event. The resolved value includes a `target` field identifying which entry won:
```javascript
const { node, target } = await observer.wait(['#success', '#error'], {
events: [DOMObserver.ADD],
})
console.log(`Matched: ${target}`)
```
Once the first matching mutation occurs, the Promise resolves and the observation stops automatically. If a `timeout` is set and elapses before any matching mutation, the Promise rejects with a `[TIMEOUT]` error.
#### `wait` method arguments
| Props | Type | Description |
| ------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `target` | Element, String, or Array | DOM element, selector, or array of either. When an array is passed, resolves on the first match across all entries. |
| `options` | Object | Options object: |
| - `events` | Array | List of [events](#events) to observe (All events are observed by default) |
| - `timeout` | Number | Duration (in ms) before rejecting the Promise with a `[TIMEOUT]` error. `0` disables the timeout. Must be `0` or a positive finite number — rejects with `[TIMEOUT]` otherwise. |
| - `attributeFilter` | Array | List of attribute names to observe (DOMObserver.CHANGE event only) |
| - `signal` | AbortSignal | An `AbortSignal` to cancel the observation. If already aborted, the Promise rejects immediately with an `AbortError`. |
| - `root` | Element or String | DOM element or CSS selector to use as the observation root. Only mutations within this subtree are observed. Defaults to `document.documentElement`. |
| - `filter` | Function | `(node, event, options?) => boolean`. Called before resolving the Promise. Return `false` to skip the event and keep waiting. |
#### Resolved value
| Props | Type | Description |
| ----------------- | --------------------- | ---------------------------------------------------------------------------------------------------- |
| `node` | Element | The matching DOM element |
| `event` | String | The event type that caused the Promise to settle |
| `target` | Element, String, or undefined | The entry from the targets array that matched. `undefined` when a single target was passed. |
| `options` | Object | Present only for `CHANGE` events: |
| - `attributeName` | String | Name of the attribute that changed |
| - `oldValue` | String or null | Value of the attribute before the mutation |
#### Events
DOMObserver static properties list all observable events.
| Props | Description |
|----------------------|-------------------------------------------------------------------------------------------|
| `DOMObserver.EXIST` | Observe whether the element is already present in the DOM at observation start |
| `DOMObserver.ADD` | Observe when the element is added to the DOM |
| `DOMObserver.REMOVE` | Observe when the element is removed from the DOM |
| `DOMObserver.CHANGE` | Observe when an attribute has changed on the element |
| `DOMObserver.EVENTS` | Array of all four events |
One or more events can be passed to the `events` option of `wait` or `watch`. By default, all events are observed.
```javascript
{ events: [DOMObserver.ADD, DOMObserver.REMOVE] }
{ events: DOMObserver.EVENTS }
```
### Check observation state
The `isObserving` getter returns `true` when an observation is currently active:
```javascript
const observer = new DOMObserver()
observer.watch('#foo', (node, event) => { /* ... */ })
console.log(observer.isObserving) // true
observer.clear()
console.log(observer.isObserving) // false
```
### Discard observation
Call the `clear` method to discard observation. It returns `this`, allowing method chaining:
```javascript
observer.clear()
// Stop and immediately restart with a different target
observer.clear().watch('#bar', onEvent)
```
> **Note:** Calling `wait()` or `watch()` on an instance that already has a pending `wait()` Promise will automatically reject that Promise with an `[ABORT]` error before starting the new observation. Handle this rejection if necessary:
>
> ```javascript
> import { DOMObserver, DOMObserverErrors } from '@untemps/dom-observer'
>
> const observer = new DOMObserver()
> observer.wait('#foo').catch((err) => {
> if (err.message.startsWith(DOMObserverErrors.ABORT)) return // replaced by a new observation
> throw err
> })
> observer.wait('#bar') // previous promise is rejected with [ABORT]
> observer.watch('#baz', onEvent) // also rejects a pending wait() with [ABORT]
> ```
## Error constants
The library exports a `DOMObserverErrors` object and a `DOMObserverErrorCode` type for reliable error handling without fragile string matching:
```typescript
import { DOMObserver, DOMObserverErrors } from '@untemps/dom-observer'
try {
await observer.wait('#foo', { timeout: 500 })
} catch (e) {
const message = (e as Error).message
if (message.startsWith(DOMObserverErrors.TIMEOUT)) {
// handle timeout
} else if (message.startsWith(DOMObserverErrors.ABORT)) {
// replaced by another observation
}
}
```
| Constant | Value | Thrown by |
|---|---|---|
| `DOMObserverErrors.TIMEOUT` | `'[TIMEOUT]'` | `wait()`, `watch()` when `timeout` elapses; also when `timeout` is an invalid value (`-1`, `NaN`, `Infinity`) |
| `DOMObserverErrors.ABORT` | `'[ABORT]'` | `wait()` when replaced by a new call |
| `DOMObserverErrors.EVENTS` | `'[EVENTS]'` | `wait()`, `watch()` when `events` array is empty |
| `DOMObserverErrors.TARGET` | `'[TARGET]'` | `wait()`, `watch()` when `target` is an invalid CSS selector |
## Example
```javascript
import { DOMObserver } from '@untemps/dom-observer'
// Continuous observation with timeout
const onError = (err) => console.error(err.message)
const observer = new DOMObserver()
observer.watch(
'.foo',
(node, event, { attributeName } = {}) => {
switch (event) {
case DOMObserver.EXIST: {
console.log('Element ' + node.id + ' exists already')
break
}
case DOMObserver.ADD: {
console.log('Element ' + node.id + ' has been added')
break
}
case DOMObserver.REMOVE: {
console.log('Element ' + node.id + ' has been removed')
break
}
case DOMObserver.CHANGE: {
console.log('Element ' + node.id + ' has been changed (' + attributeName + ')')
break
}
}
},
{
events: [DOMObserver.EXIST, DOMObserver.ADD, DOMObserver.REMOVE, DOMObserver.CHANGE],
timeout: 2000,
onError,
attributeFilter: ['class'],
}
)
```
## Development
A demo can be served for development purpose on `http://localhost:5173/` running:
```
yarn dev
```