![](\"assets/logo.svg\"){kind=logo}
Style \nA robust, production-ready library to observe CSS property changes.\nDetects browser bugs and works around them, so you don't have to.\n
\n\n[](https://www.npmjs.com/package/style-observer)\n[](https://bundlephobia.com/package/style-observer)\n\n- ✅ Observe changes to custom properties\n- ✅ Observe changes to standard properties (except `transition` and `animation`)\n- ✅ Observe changes on any element (including those in Shadow DOM)\n- ✅ [Lightweight](https://bundlephobia.com/package/style-observer), ESM-only code, with no dependencies\n- ✅ [200+ unit tests](tests) you can run in your browser of choice\n- ✅ Throttling per element\n- ✅ Does not overwrite existing transitions\n\n## Compatibility\n\n\n\n\n
\n
\n\n## Install\n\nThe quickest way is to just include straight from the [Netlify](https://www.netlify.com/) CDN:\n\n```js\nimport StyleObserver from \"https://observe.style/index.js\";\n```\n\nThis will always point to the latest version, so it may be a good idea to eventually switch to a local version that you can control.\nE.g. you can use npm:\n\n```sh\nnpm install style-observer\n```\n\nand then, if you use a bundler like Rollup or Webpack:\n\n```js\nimport StyleObserver from \"style-observer\";\n```\n\nand if you don’t:\n\n```js\nimport StyleObserver from \"node_modules/style-observer/dist/index.js\";\n```\n\n## Usage\n\nYou can first create the observer instance and then observe, like a `MutationObserver`.\nThe simplest use is observing a single property on a single element:\n\n```js\nconst observer = new StyleObserver(records => console.log(records));\nobserver.observe(document.querySelector(\"#my-element\"), \"--my-custom-property\");\n```\n\nYou can also observe multiple properties on multiple elements:\n\n```js\nconst observer = new StyleObserver(records => console.log(records));\nconst properties = [\"color\", \"--my-custom-property\"];\nconst targets = document.querySelectorAll(\".my-element\");\nobserver.observe(targets, properties);\n```\n\nYou can also provide both targets and properties when creating the observer,\nwhich will also call `observe()` for you:\n\n```js\nimport StyleObserver from \"style-observer\";\n\nconst observer = new StyleObserver(callback, {\n\ttargets: document.querySelectorAll(\".my-element\"),\n\tproperties: [\"color\", \"--my-custom-property\"],\n});\n```\n\nBoth targets and properties can be either a single value or an iterable.\n\nNote that the observer will not fire immediately for the initial state of the elements (i.e. it behaves like `MutationObserver`, not like `ResizeObserver`).\n\n### Records\n\nJust like other observers, changes that happen too close together (set the `throttle` option to configure) will only invoke the callback once,\nwith an array of records, one for each change.\n\nEach record is an object with the following properties:\n\n- `target`: The element that changed\n- `property`: The property that changed\n- `value`: The new value of the property\n- `oldValue`: The previous value of the property\n\n## Future Work\n\n- Observe pseudo-elements\n- `immediate` convenience option that fires the callback immediately for every observed element\n\n## Limitations & Caveats\n\n- You cannot observe changes on elements **not connected to a document**. However, once the elements become connected again, the observer will pick up any changes that happened while they were disconnected.\n- You cannot observe changes to `transition` and `animation` properties (and their constituent properties).\n- You cannot observe changes **caused by CSS animations** (follow [#87](https://github.com/LeaVerou/style-observer/issues/87) for updates).\n- Changes caused due to a slotted element being moved to a different slot will not be picked up.\n\n### Changing `transition` properties after observing\n\nIf you change the `transition`/`transition-*` properties dynamically on elements you are observing after you start observing them,\nthe easiest way to ensure the observer continues working as expected is to call `observer.updateTransition(targets)` to regenerate the `transition` property the observer uses to detect changes.\n\nIf running JS is not an option, you can also do it manually:\n\n1. Add `, var(--style-observer-transition, --style-observer-noop)` at the end of your `transition` property.\n E.g. if instead of `transition: 1s background` you'd set `transition: 1s background, var(--style-observer-transition, --style-observer-noop)`.\n2. Make sure to also set `transition-behavior: allow-discrete;`.\n\n## Prior Art\n\nThe quest for a JS style observer has been long and torturous.\n\n- Early attempts used polling. Notable examples were [`ComputedStyleObserver` by Keith Clark](https://github.com/keithclark/ComputedStyleObserver)\n and [`StyleObserver` by PixelsCommander](https://github.com/PixelsCommander/StyleObserver)\n- [Jane Ori](https://propjockey.io) was the first to do better than polling, her [css-var-listener](https://github.com/propjockey/css-var-listener) using a combination of observers and events.\n- [css-variable-observer](https://github.com/fluorumlabs/css-variable-observer) by [Artem Godin](https://github.com/fluorumlabs) pioneered using transition events to observe property changes, and used an ingenious hack based on `font-variation-settings` to observe CSS property changes.\n- Four years later, [Bramus Van Damme](https://github.com/bramus) pioneered a way to do it \"properly\" in [style-observer](https://github.com/bramus/style-observer),\n thanks to [`transition-behavior: allow-discrete`](https://caniuse.com/mdn-css_properties_transition-behavior) becoming Baseline and even [blogged about all the bugs he encountered along the way](https://www.bram.us/2024/08/31/introducing-bramus-style-observer-a-mutationobserver-for-css/).\n\nWhile `StyleObserver` builds on this body of work, it is not a fork of any of them.\nIt was written from scratch with the explicit goal of extending browser support and robustness.\n[Read the blog post](https://lea.verou.me/2025/style-observer/) for more details.\n\n| Feature | \n\tChrome | \n\tSafari | \n\tFirefox | \n\t% of global users | \n
|---|---|---|---|---|
| Custom properties | \n\t117 | \n\t17.4 | \n\t129 | \n\t89% | \n
| Custom properties (registered with an animatable type) | \n\t97 | \n\t16.4 | \n\t128 | \n\t93% | \n
| Standard properties (discrete)\n\t Except transition, animation\n\t | \n\t117 | \n\t17.4 | \n\t129 | \n\t89% | \n
| Standard properties (animatable) | \n\t97 | \n\t15.4 | \n\t104 | \n\t95% | \n