Csstag NPM | npm.io

csstag

Use CSS Modules as tagged templates in a browser and Node.js. Example:

import css from 'csstag';
const styles = css`
  .root {
    color: red;
  }
`;
<div class={styles.root} />;

Demo: https://sgtpep.github.io/csstag/demo/.

Benefits over other CSS-in-JS libraries

The majority of CSS-in-JS libraries are opinionated and bloated, while csstag relies only on CSS Modules which is a widely adopted and well-understood open specification very close to standard CSS with a number of implementations.
With CSS Modules you can write any valid CSS.
It's framework agnostic and may be used together with React, Preact, any other library or framework or no framework at all.
Has zero dependencies (it made possible by bundling them in one file).
Provided also as a native ES module which can be imported directly in browser without bundlers: import css from './node_modules/csstag/index.min.js'; or import css from 'https://unpkg.com/csstag';
Can by excluded from production code and replaced with static CSS using a Babel plugin babel-plugin-csstag.

Installation

Using `npm`

npm install csstag

Using `yarn`

yarn add csstag

Importing

From Node.js

const { css } = require('csstag');

Or from .mjs:

import css from 'csstag';

From a bundler (webpack, etc.)

import css from 'csstag';

From a browser

If you don't use a bundler (webpack, etc.) but prefer native ES6 modules instead (<script type="module"></script>):

import css from './node_modules/csstag/index.min.js';

Or use unpkg CDN:

import css from 'https://unpkg.com/csstag';

Usage

Once imported you can declare a CSS module as a tagged template using the tag function css:

import css, { appendStyles } from 'csstag';

const styles = css`
  .foo {
    color: red;
  }
  .bar {
    color: blue;
  }
`;

It returns an object with all exported class names in it:

console.log(styles);
{ foo: 'csstag__foo___LTk0O', bar: 'csstag__bar___LTk0O' }

The module csstag contains the array of compiled styles called styles, which is populated with a new item every time css tag function is being called, and now contains:

[
  `.csstag__foo___LTk0O {
    color: red;
  }
  .csstag__bar___LTk0O {
    color: blue;
  }`,
];

You may want to append all newly added items from that array as a stylesheet as <style> in your document's <head> using the function appendStyles imported earlier (in React-like projects it makes sense to call it together with render() in your entry point):

appendStyles();

If you're using Prettier, it will format the CSS code inside css tag function.

csstag itself comes as a bundle containing some heavy-weight packages like PostCSS and has a size of ~100K minimized. To exclude it from production code and leave only compiled styles you might use a Babel plugin babel-plugin-csstag.

API

css: The main tag function itself which can be imported as a default or named import.
appendStyles(): Appends all stylesheets built from recent uses of css tag function as <style> in your document's <head>. The consecutive calls to this function will produce no effect until next calls to css tag function. Uses popStyles() internally.
popStyles(): Empties and returns a list of stylesheets built from recent uses of css tag function.
styles: A list of recently built stylesheets for direct access.

If you don't like storing a list of built stylesheets in csstag module's styles array, or you're dealing, for instance, with multiple applications at once, you may create new functions bound to any other array using .bind():

import csstag, { appendStyles } from 'csstag';

const styles = [];
const css = csstag.bind(styles);
css`
  .root {
    color: red;
  }
`;
appendStyles.bind(styles)();

Options

To pass options pass an object with them as a second argument of .bind():

import csstag from 'csstag';

const css = csstag.bind(null, { prefix: 'myapp' });

modulesLocalByDefault: Options passed to postcss-modules-local-by-default (default: null).
modulesParser: Options passed to postcss-modules-parser (default: null).
modulesScope: Options passed to postcss-modules-scope (default: { generateScopedName: ... }, a function generating compiled class names).
modulesValues: Options passed to postcss-modules-values (default: null).
pluginsBefore: An array of PostCSS plugin before the default plugin list (default: []).
plugins: An array of PostCSS plugins added to the end of the default plugin list (default: []).
prefix: A first component of a generated class name (default: csstag).
process: Options passed to the process() method of PostCSS (default: null).
hashLength: Class name hash length to minimize collision risk (default: 5).