JavaScript API

Everything lives on the global css object.

css.open(url, [noCache])#

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

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().

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])#

Changes a variable and updates every rule that uses it:

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)#

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

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

css.get_computed(sheet, name, [i])#

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

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

css.update_vars()#

Recalculates every auto-updating variable. 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.

css.update_vars();

Event: css_ready#

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

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

css.on(type, selector, handler)#

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.

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

css.pseudo(element, type)#

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

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

css.pseudos(selector)#

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

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:

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.