# css-observe

> Fire a custom event whenever an element matching a specified selector is added.

Latest version **0.0.61** (published 2022-08-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install css-observe
pnpm add css-observe
yarn add css-observe
bun add css-observe
```

## Health

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

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.61 |
| Published | 2022-08-29 |
| First published | 2018-09-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 35.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | bahrus |
| Maintainers | bahrus |
| Keywords | web-components, web-component, custom-element, custom-elements, css |

## Links

- npm: https://www.npmjs.com/package/css-observe
- Repository: https://github.com/bahrus/css-observe
- Homepage: https://github.com/bahrus/css-observe#readme
- Issues: https://github.com/bahrus/css-observe/issues
- npm.io page: https://npm.io/package/css-observe

## Dependencies (3)

- [trans-render](https://npm.io/package/trans-render.md) 0.0.578
- [xtal-element](https://npm.io/package/xtal-element.md) 0.0.514
- [be-exportable](https://npm.io/package/be-exportable.md) 0.0.28

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 0.0.61 (latest) — 2022-08-29
- 0.0.60 — 2022-08-22
- 0.0.59 — 2022-04-10
- 0.0.58 — 2021-10-18
- 0.0.57 — 2021-10-09
- 0.0.56 — 2021-10-06
- 0.0.55 — 2021-10-02
- 0.0.54 — 2021-08-31
- 0.0.53 — 2021-08-31
- 0.0.52 — 2021-08-24
- 0.0.51 — 2021-08-20
- 0.0.49 — 2021-08-18
- 0.0.48 — 2021-08-18
- 0.0.47 — 2021-08-18
- 0.0.46 — 2021-08-18
- … 46 more at https://npm.io/package/css-observe/versions

## README

[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/css-observe)

<a href="https://nodei.co/npm/css-observe/"><img src="https://nodei.co/npm/css-observe.png"></a>

[![Actions Status](https://github.com/bahrus/css-observe/workflows/CI/badge.svg)](https://github.com/bahrus/css-observe/actions?query=workflow%3ACI)

<img src="https://badgen.net/bundlephobia/minzip/css-observe@0.0.48">

# css-observe

css-observe is a "web component as a service" that specializes in watching for DOM elements matching a CSS selector appearing within the same Shadow DOM realm (or within a specified "closest" selector).  When such an element is spotted, css observe can perform up to four distinct actions:

1.  Fire an event.
2.  Perform a [DTR transform](https://github.com/bahrus/trans-render) on the newly discovered element ("target"). 
3.  Perform a DTR transform on the host's shadow DOM (or document when outside any shadow DOM). 
4.  Perform an action contained within a script tag contained nearby (preferably before).  


## [API Reference](https://bahrus.github.io/wc-info/cdn-base.html?npmPackage=css-observe)


```html
<div>
    <script id=my-script nomodule be-exporting>
        export const action = (target) => {
            target.setAttribute('I am here', '');
        }
    </script>
    <css-observe observe selector="div[test]" data-name="Clive" script-ref=my-script  options='{
        "targetTransform": {
            "span": "dataset.name"
        },
        "hostTransform":{
            "section": [{},{},{},"<span>found it</span>"]
        }
    }'>
    </css-observe>

    <div test>
        I am here, <span></span>
    </div>
    <section></section>
</div>
```

Another attribute / property, within-closest/withinClosest, restricts matches to those within the closest ancestry of the css-observe element matching the within-closest value.

css-observe will fire event: latest-match-changed, and the newly added element can be obtained from event.detail.value.

It will only observe the selector within the same Shadow DOM realm where the element is placed.  If the element is placed outside any ShadowDOM, it will observe the selector only outside any ShadowDOM.  

## Implementation 

Based off of an idea found [here](https://davidwalsh.name/detect-node-insertion).  I agree:  How cool is that?


## Viewing Your Element

```
$ npm install
$ npm run serve
```

## Running Tests

```
$ npm run test
```

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