@ptb/style

CSS compiler for maintainable, predictable styles with the minimum possible output. Eliminate the cognitive overhead of regular CSS: coming up with class names, composing styles for variants, specificity issues, and style ordering. Supports client-side rendering, server-side rendering, zero-runtime, or a combination.

@ptb/style

All the features of CSS with the ease of inline styles.
Explore the docs »

View Demo · Report Bug · Request Feature

About The Project

I've been a web developer for over 25 years*, and in that time I've used vanilla CSS, Sass, Styletron, Styled Components, and everything in between. I've always wanted a CSS architecture that is predictable, maintainable, and that results in the absolute minimum possible output. I've distilled all of my experience into this tool.

This is my way of giving back to the web development community.

No More Naming

Class names are generated automatically in a consistent and predictable way. The same input will result in the same output, and is based on the CSS property used and their values; whether rendered at build time, server-side rendered, or at runtime in the browser.

Easy Variants

Pass an array of objects as input and they will be deep merged. Start with a base set of styles and then any modifications as a second object. Matching styles will be overridden and won't appear in the output class names or CSS if not used.

Optimized Output

Styles are cached, de-duplicated, automatically re-used, and minimized. If you use color: red hundreds of times, it will still only result in one declaration in the CSS (at most per each media query or @supports block).

Setup Not Required

Ideal for trying quick design ideas in Create React App, CodeSandbox, and others without setting up theme providers, wrappers, special components, props, or build configuration. One import and you're ready to go.

When you're ready to deploy to production, add /macro to the import path and configure your framework to save the cached styles. Zero-runtime is easy.

So Many Shortcuts

Using $-prefixed variables, set up CSS property abbreviations, media query shortcuts, vendor prefixes, or groups of style snippets anywhere. Styled System shorthands are built-in and can be extended with your own. Several media query shortcuts are pre-defined and add custom queries that make sense for your project. Media queries can be used at the top of a group of styles, at the bottom under a CSS property, or nested inside of other media queries.

(back to top)

Flexibility

Dynamic Runtime

At its core, it is a JavaScript function that takes CSS styles stored as JS objects and returns class names that those styles represent. The core of this library is a single JavaScript function that accepts a JavaScript object containing styles as input, which are parsed, cached, de-duplicated, and applied to the page at runtime responding dynamically as events make changes to the page.

…or Zero-Runtime

Alternatively, styles can be "compiled away" leaving just class names and a minimized CSS file by using the Babel macro (and one-time setup).

If you need client-side rendering (CSR), server-side rendering (SSR), or static at build time (SSG), it's covered.

Media Queries

Media queries can be specified at the top of a group of styles, at the bottom under the CSS property itself, or anywhere in between. Media queries can also be nested.

Any and All Selectors

Use type selectors, class selectors, ID selectors, universal selectors, attribute selectors, state selectors, sibling, child, or descendant selectors, pseudo classes, and pseudo elements. The & nesting selector from Sass is also supported. In addition, %-prefixed placeholder class names and a special "self-selector" can be used when needed. The self- selector re-uses the & character to group a set of styles under a single class name. Atomic or grouped class names: it's your choice.

Simplicity

Styles are declarable. This tool does one thing: converts style rules applies them to the page. There is only one function to learn and if you know CSS and JavaScript already, it will look very familiar. It parses styles, selectors, shortcuts, and media queries using a single function. It creates unique class names automatically. Styles are ordered simply and consistently. Selectors are parsed, de-duplicated, and grouped with identical declarations automatically.

Decrease Cognitive Overhead

Don't worry about naming things, style order, specificity, compressing output, build tools, plugins, etc. Have I used this before? If I change it here, what else will change? What should I name this? Keeping all those concerns and details in mind is a thing of the past.

Maintainable

All styles are stored as plain JavaScript objects. Code style preferences can be enforced using ESLint or, if using JSON, with various JSON tools like the included merge-json CLI tool. Works for a single developer or a team. Avoids bikeshedding as much as possible.

(back to top)

Customization

Theme Variables

Store values in an easily accessible $-prefixed variable namespace. Define values for colors, fonts, spacing, and utilize them anywhere in your project. Native CSS custom properties (CSS variables) are also supported. Both $-prefixed variables and custom properties can also be scoped to apply defferently in certain media queries if desired.

@media Shortcuts

Set shortcuts for common media queries using the $media key. Define an object with the key you'd like to use and the value as the expanded media query feature (or type). Several media queries are pre-defined by default, but can be extended or overridden if desired. Shortcuts are built-in, but can be extended using your own.

CSS Property Shortcuts

Set abbreviations for CSS properties using $properties key. These are merged with the built-in Styled System shorthands.

Code Snippets

Keep reusable groups of styles in $-prefixed variables and retrieve them using the $-prefixed variable name and the value of true.

Vendor Prefixes

Set an array of vendor prefixes for any property using the $prefixes key.

(back to top)

Installation

Add @ptb/style to your project:

• npm

  npm install @ptb/style
  

• yarn

  yarn add @ptb/style
  

(back to top)

Usage

Import the css function and use with the className prop:

import { css } from "@ptb/style"

export function ({ children }) {
  return (
    <div className={css({ })}>
      {children}
    </div>
  )
}

(back to top)

Documentation

Be sure to check out the documentation where you'll find live examples for all of the features mentioned above.

(back to top)

License

Distributed under the Apache License. See LICENSE for more information.

(back to top)

Acknowledgments

• Thanks to Austin Appleby for MurmurHash3.
• Thanks to Gary Court for murmurhash-js.
• Thanks to Andrey Sitnik for nanoid.

(back to top)