# JavaScript API — css.open, css.set, css.get and events

> Reference for the CSS Post Processor JavaScript API - css.open(), css.defaults, css.set(), css.get(), css.get_computed(), css.update_vars() and the css_ready event.

Source: https://csspp.dev/docs/javascript-api/


Everything lives on the global `css` object.

## css.open(url, [noCache]) {#css-open}

Fetches a stylesheet, processes it and injects the result into `<style id="name">`, where `name` is the file name without its extension.

```js
css.open('/css/site.css');          // -> <style id="site">
css.open('/css/site.css', true);    // bypass the browser cache (adds ?R=timestamp)
css.open('#main');                  // process an existing <style id="main"> in place
```

You can open several stylesheets. With `css.defaults.invisible` on, the page stays hidden until all of them are processed.

## css.defaults

Set these before the first `css.open()`.

```js
css.defaults.debug = 0;        // 1 = throw on undefined variables and expose window.css_vars
css.defaults.invisible = 1;    // hide <html> until stylesheets are processed
css.defaults.localCache = 0;   // 1 = render from a localStorage copy, then refresh
css.defaults.resizing = 100;   // ms throttle for auto-updating variables
```

## css.set(sheet, name, [value]) {#css-set}

Changes a variable and updates every rule that uses it:

```js
css.set('site', 'brand', '#e11d48');
```

`sheet` is the stylesheet name, `name` is the variable name without `$`, including the `!` for auto-updating variables. Pass values as strings: empty values such as `0` and `''` are ignored, so use `'0'`. Calling `css.set(sheet, name)` without a value re-evaluates the variable, which is useful for JavaScript expressions.

## css.get(sheet, name) {#css-get}

Returns the variable's raw definition, the value or expression as written:

```js
css.get('site', 'brand');            // "#0ea5e9"
```

## css.get_computed(sheet, name, [i]) {#css-get-computed}

Returns the computed value for each place the variable is used. Pass `i` for a single one:

```js
css.get_computed('site', 'vw!');     // e.g. [1280]
```

## css.update_vars() {#css-update-vars}

Recalculates every [auto-updating variable](/docs/variables/#auto-updating-variables). css-pp calls this itself on resize, on orientation change and after the page has loaded. Call it yourself after a layout change the browser doesn't report, such as a script that resizes a container.

```js
css.update_vars();
```

## Event: css_ready {#css-ready}

Fired on `document` once per stylesheet, after it has been processed and the DOM is ready. `event.id` is the stylesheet name.

```js
document.addEventListener('css_ready', function (e) {
  if (e.id === 'site') initSlider();
});
```

## css.on(type, selector, handler) {#css-on}

A delegated listener on the document. With a pseudo-element in the selector, it fires only when the pointer is on that pseudo-element; `this` is the element and `e.pseudo` is `'::after'`. Returns a function that removes the listener.

```js
var stop = css.on('click', '.chip::after', function (e) { this.remove(); });
css.on('click', 'dialog::backdrop', function () { this.close(); });
```

## css.pseudo(element, type) {#css-pseudo}

An object for one element's pseudo-element: `style(prop)`, `set(prop, value)` / `set({...})`, `text`, `exists`, `contains(x, y)`, `rect()` and `animate(keyframes, options)`.

```js
css.pseudo(el, '::after').set('color', 'red').text = '3 new';
```

## css.pseudos(selector) {#css-pseudos}

Every rendered pseudo-element that matches, as `css.pseudo()` objects: `css.pseudos('.card::after')`. Full details: [Pseudo-elements in JavaScript](/docs/pseudo-elements/).

## Attributes you can use

The state, content and index features add attributes to elements. You can read them, or use them in other CSS and scripts:

| Attribute | Added by |
|---|---|
| `data-css-seen`, `data-css-seen-30`, `data-css-seen-300px` | `:seen`, `:seen(30%)`, `:seen(300px)` (same pattern for `:in-view`) |
| `data-css-stuck`, `data-css-overflowing` | `:stuck`, `:overflowing` |
| `data-css-current`, `data-css-current-exact` | `:current`, `:current(exact)` |
| `data-css-scrolled`, `data-css-scrolled-80px` | `:scrolled`, `:scrolled(80px)` |
| `data-css-scrolling-down`, `data-css-scrolling-up` | `:scrolling-down`, `:scrolling-up` |
| `data-css-scroll-start`, `data-css-scroll-end` | `:scroll-start`, `:scroll-end` |
| `data-css-target-in-view` | `:target-in-view` |
| `data-css-loaded`, `data-css-broken`, `data-css-wrapped` | `:loaded`, `:broken`, `:wrapped` |
| `data-css-filled`, `data-css-dirty`, `data-css-offline`, `data-css-idle-30s` | `:filled`, `:dirty`, `:offline`, `:idle(30s)` |
| `data-css-after-hover`, `data-css-before-active`, … | `::after:hover`, `::before:active` and the other two combinations |
| `data-css-contains-N`, `data-css-cmp-N` | `:contains()` and numeric comparisons, numbered per distinct condition |
| `data-css-i` | Per-element values (`$[index]`, `$[random()]`, `$[attr()]`, `fit()`): a stable id for each element |

The pattern is always `data-css-` plus the selector name, plus its argument with anything but letters and digits removed.

## Helper globals

css-pp also defines two small utilities on `window`, which you may use:

- `fireTimer(id, fn, ms, param)` runs `fn` now, then at most every `ms` while it keeps being called. It is a throttle with a trailing call.
- `new sizeObserver(fn).observe(elements)` calls `fn` when any of the elements changes size. It uses `ResizeObserver`, or polling in old browsers.