# qsa-observer

> handle elements lifecycle through CSS selectors

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

## Install

```sh
npm install qsa-observer
pnpm add qsa-observer
yarn add qsa-observer
bun add qsa-observer
```

## Health

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

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.0.2 |
| Published | 2026-04-27 |
| First published | 2020-07-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 12.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Andrea Giammarchi |
| Maintainers | webreflection |
| Keywords | querySelectorAll, MutationObserver |

## Links

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

## Dependencies (2)

- [shadow-observer](https://npm.io/package/shadow-observer.md) ^0.1.7
- [element-notifier](https://npm.io/package/element-notifier.md) ^2.0.3

## Alternatives

- [gamedig](https://npm.io/package/gamedig.md) — 29.3K weekly downloads
- [join-monster](https://npm.io/package/join-monster.md) — 12.8K weekly downloads
- [masked](https://npm.io/package/masked.md) — 5.5K weekly downloads
- [@comunica/actor-query-process-explain-logical](https://npm.io/package/@comunica/actor-query-process-explain-logical.md) — 4.7K weekly downloads
- [@veracity/vui](https://npm.io/package/@veracity/vui.md) — 4.6K weekly downloads

## Recent versions

- 4.0.2 (latest) — 2026-04-27
- 4.0.1 — 2026-04-27
- 4.0.0 — 2026-04-23
- 3.0.2 — 2023-03-04
- 3.0.1 — 2022-06-02
- 3.0.0 — 2022-05-23
- 2.0.2 — 2021-05-05
- 2.0.1 — 2021-05-05
- 2.0.0 — 2021-04-13
- 1.1.6 — 2020-09-24
- 1.1.5 — 2020-08-07
- 1.1.4 — 2020-08-07
- 1.1.3 — 2020-08-06
- 1.1.2 — 2020-08-03
- 1.1.1 — 2020-08-02
- … 9 more at https://npm.io/package/qsa-observer/versions

## README

# qsa-observer

![bird watch](./qsa-observer-head.jpg)

<sup>**Social Media Photo by [Kevin Maillefer](https://unsplash.com/@kmaillefer) on [Unsplash](https://unsplash.com/)**</sup>


Given an array of selectors, handles any matching element that was either connected, or disconnected, from an observed element, or document.


### Differently from MutationObserver

  * each element is granted to be handled, whenever it's observed via one, or more, selectors
  * all observed elements will pass through `handle(element, connected, selector)` utility, per each matching selector
  * elements injected through `innerHTML`, or created offline, will be handled too once live


### Example

```js
import QSAO from 'qsa-observer';

// an Array of CSS selectors to observe
const query = ['div'];

// where to observe mutations, document by default
const root = document;

const {
  drop,     // an utility to drop a list of elements from being considered live
  flush,    // an utility to flush synchronously all queued mutations
  observer, // the MutationObserver created by QSAO(...)
  parse     // an utility to parse new elements
            // (i.e. after adding a selector to the query list)
} = QSAO({
  query,  // list of selectors to observe
  root,   // optional, as it's document by default

  // the method that receives all elements that match one or more
  // selectors in the query, and are either connected or disconnected
  handle(element, connected, selector) {
    const event = connected ? 'connected' : 'disconnected';
    console.log(element, event, selector);
  }
});

// example: add another selector to observe and pass through the handle
const observeMore = selector => {
  if (!query.includes(selector)) {
    query.push(selector);
    parse(root.querySelectorAll(selector));
  }
};

// example: watch 'p' nodes too after a second
setTimeout(observeMore, 1000, 'p');
```


### Libraries based on qsa-observer

  * [custom-elements-ie](https://github.com/WebReflection/custom-elements-ie#readme)
  * [custom-elements-builtin](https://github.com/WebReflection/custom-elements-builtin#readme)
  * [as-custom-element](https://github.com/WebReflection/as-custom-element#readme)
  * [wicked-elements](https://github.com/WebReflection/wicked-elements#readme)
  * [hooked-elements](https://github.com/WebReflection/hooked-elements#readme)

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