Awesome
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';
orimport 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 ofcss
tag function as<style>
in your document's<head>
. The consecutive calls to this function will produce no effect until next calls tocss
tag function. UsespopStyles()
internally.popStyles()
: Empties and returns a list of stylesheets built from recent uses ofcss
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 ofPostCSS
plugin before the default plugin list (default:[]
).plugins
: An array ofPostCSS
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 theprocess()
method ofPostCSS
(default:null
).hashLength
: Class name hash length to minimize collision risk (default:5
).