Skip to content
Runtime CSS modules with SASS like preprocessing
JavaScript CSS HTML
Branch: master
Clone or download
bratberg and lukejacksonn Adds support for external stylesheets with absolute urls (#9)
* Update index.js

* Update test.js

* Update package.json

* Update test.js

* Update index.js

* Update test.js

* Update README.md
Latest commit 7ed0eae Jan 21, 2020

README.md

csz

Runtime CSS modules with SASS like preprocessing

A framework agnostic css-in-js solution that uses stylis to parse styles from tagged template literals and append them to the head of the document at runtime. Loading in stylesheets dynamically – from .css files – is supported out of the box, so you can write your styles in .css files and import them via url without having to worry about flashes of unstyled content.

Features

  • Efficient caching of styles
  • Import styles from regular .css files
  • Available as an ES module (from unpkg.com)
  • Styles scoped under unique namespaces .csz-lur7p80ssnq
  • Global style injection :global(selector)
  • Nested selectors a { &:hover {} }
  • Vendor prefixing -moz-placeholder
  • Flat stylesheets color: red; h1 { color: red; }
  • Minification of appended styles
  • Keyframe and animation namespacing

Usage

The package is designed to be used as an ES module. You can import it directly from unpkg.com:

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

// static
const inlined = css`background: blue;`; // generate class name for ruleset

// dynamic (from stylesheet)
const relative = css`/index.css`; // generate class name for file contents
const absolute = css`https://example.com/index.css`; // generate class name for file contents

Both variations (static and dynamic) are sync and return a string in a format similar to csz-b60d61b8. If a ruleset is provided as a string then it is processed immediately but if a filepath is provided then processing is deferred until the contents of the file has been fetched and parsed.

NOTE: File paths starting with / must be relative to the current hostname, so if you are running your app on example.com and require /styles/index.css then csz will try fetch it from example.com/styles/index.css.

Styles imported from a file are inevitably going to take some amount of time to download. Whilst the stylesheet is being downloaded a temporary ruleset is applied to the element which hides it (using display: none) until the fetched files have been processed. This was implemented to prevent flashes of unstyled content.

See below for an example of what a raw ruleset might look like and how it looks like after processing.

Example stylesheet (unprocessed)
font-size: 2em;

// line comments
/* block comments */

:global(body) {background:red}

h1 {
  h2 {
    h3 {
      content:'nesting'
    }
  }
}

@media (max-width: 600px) {
  & {display:none}
}

&:before {
  animation: slide 3s ease infinite
}

@keyframes slide {
  from { opacity: 0}
  to { opacity: 1}
}

& {
  display: flex
}

&::placeholder {
  color:red
}
Example stylesheet (processed)
  .csz-a4B7ccH9 {font-size: 2em;}

  body {background:red}
  h1 h2 h3 {content: 'nesting'}

  @media (max-width: 600px) {
    .csz-a4B7ccH9 {display:none}
  }

  .csz-a4B7ccH9:before {
    -webkit-animation: slide-id 3s ease infinite;
    animation: slide-id 3s ease infinite;
  }


  @-webkit-keyframes slide-id {
    from { opacity: 0}
    to { opacity: 1}
  }
  @keyframes slide-id {
    from { opacity: 0}
    to { opacity: 1}
  }

  .csz-a4B7ccH9 {
    display:-webkit-box;
    display:-webkit-flex;
    display:-ms-flexbox;
    display:flex;
  }

  .csz-a4B7ccH9::-webkit-input-placeholder {color:red;}
  .csz-a4B7ccH9::-moz-placeholder {color:red;}
  .csz-a4B7ccH9:-ms-input-placeholder {color:red;}
  .csz-a4B7ccH9::placeholder {color:red;}

Example

This library is framework agnostic but here is a contrived example of how you can style a React component conditionally based upon some state; demonstrating switching between static and dynamic styles on the fly.

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

export default () => {
  const [toggle, setToggle] = React.useState(false);
  return (
    <div
      className={toggle
        ? css`/index.css`
        : css`background: blue;`}
    >
      <h1>Hello World!</h1>
      <button onClick={e => setToggle(!toggle)}>Toggle</button>
    </div>
  );
};

Implementation

I was inspired by emotion and styled-components but unfortunately neither of these packages expose an es module compatible build and come with quite a lot of extraneous functionality that isn't required when the scope of the project is restricted to runtime only class name generation and ruleset isolation.

You can’t perform that action at this time.