Style Observer: Run JavaScript When CSS Properties Change

Introduction

Style Observer is a robust, production-ready JavaScript library by Lea Verou and Dmitry Sharabin, designed to detect and respond to changes in any CSS property. It provides a powerful mechanism to run JavaScript code whenever a CSS property on an element changes, offering a solution for dynamic web interfaces. The library is lightweight, dependency-free, and meticulously tested to ensure compatibility across various browsers, even detecting and working around known browser bugs.

Key features include:

• Observe changes to custom properties
• Observe changes to standard properties (except transition and animation)
• Observe changes on any element (including those in Shadow DOM)
• Lightweight, ESM-only code, with no dependencies
• 200+ unit tests you can run in your browser of choice
• Throttling per element
• Does not overwrite existing transitions

Installation

The quickest way to get started is by including Style Observer directly from a CDN:

import StyleObserver from "https://observe.style/index.js";

For more controlled environments, you can install it via npm:

npm install style-observer

Then, if you use a bundler like Rollup or Webpack:

import StyleObserver from "style-observer";

And if you don’t use a bundler:

import StyleObserver from "node_modules/style-observer/dist/index.js";

Examples

Style Observer's API is similar to other browser observers. You can create an observer instance and then observe elements and properties.

Observing a single property on a single element:

const observer = new StyleObserver(records => console.log(records));
observer.observe(document.querySelector("#my-element"), "--my-custom-property");

You can also observe multiple properties on multiple elements:

const observer = new StyleObserver(records => console.log(records));
const properties = ["color", "--my-custom-property"];
const targets = document.querySelectorAll(".my-element");
observer.observe(targets, properties);

Alternatively, you can provide targets and properties directly when creating the observer:

import StyleObserver from "style-observer";

const observer = new StyleObserver(callback, {
	targets: document.querySelectorAll(".my-element"),
	properties: ["color", "--my-custom-property"]
});

Each record passed to the callback contains target, property, value, and oldValue, providing detailed information about the change.

Why Use Style Observer?

Style Observer stands out as a sophisticated solution for monitoring CSS changes, addressing a long-standing challenge in web development. Unlike earlier attempts that relied on polling, this library leverages modern browser capabilities and innovative techniques to provide a highly efficient and accurate observation mechanism. It is built from scratch to extend browser support and robustness, ensuring reliable performance across different environments.

Key advantages include its ability to observe both custom and standard CSS properties, comprehensive browser compatibility (as detailed in its documentation), and a lightweight footprint with no external dependencies. The project boasts over 200 unit tests, highlighting its commitment to stability and bug detection. For developers needing precise control over UI reactions to style changes, Style Observer offers a production-ready and thoroughly vetted tool.

Links

• GitHub Repository: LeaVerou/style-observer
• npm Package: style-observer
• Official Blog Post by Lea Verou