# live-node-list

> An alternative to NodeList which keeps collections up to date when changes to the DOM occur

Latest version **2.1.1** (published 2021-09-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install live-node-list
pnpm add live-node-list
yarn add live-node-list
bun add live-node-list
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 2.1.1 |
| Published | 2021-09-03 |
| First published | 2018-08-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 63.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | James Dinsdale |
| Maintainers | molovo |

## Links

- npm: https://www.npmjs.com/package/live-node-list
- Repository: https://github.com/molovo/live-node-list
- Homepage: https://github.com/molovo/live-node-list#readme
- Issues: https://github.com/molovo/live-node-list/issues
- npm.io page: https://npm.io/package/live-node-list

## Dependencies (1)

- [decko](https://npm.io/package/decko.md) ^1.2.0

## Recent versions

- 2.1.1 (latest) — 2021-09-03
- 3.0.0-7 (beta) — 2026-05-08
- 3.0.0-6 — 2025-12-18
- 3.0.0-5 — 2025-12-18
- 3.0.0-4 — 2025-12-18
- 3.0.0-3 — 2025-07-23
- 3.0.0-2 — 2025-07-23
- 3.0.0-1 — 2025-07-23
- 3.0.0-0 — 2024-11-15
- 2.0.0-8 — 2019-08-15
- 2.0.0-7 — 2019-02-13
- 2.0.0-6 — 2019-01-23
- 2.0.0-5 — 2018-11-28
- 2.0.0-4 — 2018-11-20
- 2.0.0-3 — 2018-11-20
- … 6 more at https://npm.io/package/live-node-list/versions

## README

# LiveNodeList

An alternative to NodeList which keeps collections up to date when changes to
the DOM occur

## Install

```
npm install live-node-list
```

## Usage

Use the LiveNodeList constructor anywhere you would normally use
`Element.querySelectorAll()`.

```js
const items = new LiveNodeList('.item')
```

LiveNodeList creates a [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) instance to monitor for childList and
subtree changes within the parent, and refreshes the list of items whenever the
childList changes.

By default, LiveNodeList selects within `document.documentElement`, but you
can limit the scope of the query by passing in a parent element as a second
parameter

```js
const items = new LiveNodeList('.item', document.getElementById('my-container'))
```

LiveNodeList also maintains an internal list of event listeners, and exposes
`addEventListener()` and `removeEventListener()` methods. Adding an event
listener will cascade it to each of the items in the list, and will handle
attaching the event listener to new items when the list of items changes.

```js
const fn = () => {}
const items = new LiveNodeList('.item')
items.addEventListener('click', fn)
items.removeEventListener('click', fn)
```

As well as applying event listeners to the items in the list, you can also add
'delegated' event listeners - that is event listeners attached to another element,
that are removed when there are no items in the LiveNodeList, and added again
once items are present.

This is useful, for example adding an event listener for
the scroll event to the `window`, within which you perform some modification to
the items in the list. When there are no items in the list, the event listener is
redundant, so removing it will increase scroll performance.

```js
const items = new LiveNodeList('.item')
const onScroll = e => {
  items.forEach(item => item.innerHTML = item.getBoundingClientRect().top)
}

items.addDelegatedEventListener(window, 'scroll', onScroll, { passive: true })
```

LiveNodeList also triggers its own `update` event when the list of items
changes.

```js
const items = new LiveNodeList('.item')
items.on('update', (newItems, oldItems) => {
  // Do something
})
```

The other supported events are as follows:

* `start` - fired when observation first begins
* `pause` - fired when the `pause()` method is called
* `resume` - fired when the `resume()` method is called
* `eventListeners:add` - fired when an event listener is added to the list
* `eventListeners:remove` - fired when an event listener is removed from the list
* `eventListeners:attach` - fired when the stored event listeners are attached
* `eventListeners:detach` - fired when the stored event listeners are detached
* `eventListeners:purge` - fired when the list of event listeners is purged

If your update method triggers HTML changes within the parent, you can get caught in an infinite loop, where those changes trigger the update function recursively. If this happens, you can pause and resume LiveNodeList's observation to prevent recursive calls while you make the necessary updates.

```js
const items = new LiveNodeList('.item')
items.on('update', (newItems, oldItems) => {
  items.pause()

  newItems.forEach(item => {
    // Do something which updates item's HTML
  })

  items.resume()
})
```

## LiveElement

LiveNodeList also comes with a `LiveElement` class, which is used to attach a single element, and is useful as a replacement for `document.getElementById` which provides the same API as LiveNodeList.

```js
import { LiveElement } from 'live-node-list'

const item = new LiveElement('#item')
item.addEventListener('change', fn)

item.on('update', (newItem, oldItem) => {
  // Do something
})
```

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