styletron: A JavaScript repository from Earlo

Universal, high-performance JavaScript styles.

What is Styletron?

Styletron is a universal CSS-in-JS engine built from the ground up for high-performance. Features include:

Advanced critical rendering path optimization of server-rendered pages

Dynamic generation of inlineable critical stylesheets with minimum possible size and parse times
- Automatic generation of maximally compressed "atomic" critical CSS via declaration-level deduplication
- Automatic declaration-level dead CSS elimination - only actually used declarations get included in output
Native media query and pseudo selector support for full critical CSS without JavaScript

Efficient dynamic client-side styles

Hyper-granular memoization to avoid making unnecessary modifications to stylesheet
Fast cache hydration of server-rendered styles to prevent re-rendering of server-rendered styles
Use of CSSStyleSheet rule injection ensuring only new styles get parsed

Check out the introductory blog post to learn more

For framework and library authors

The core Styletron module is a small, generic utility that is entirely independent of React so it can be integrated into virtually any web app. Additionally, many CSS-in-JS interfaces can be implemented with Styletron as a result of its low-level, unopinionated API.

Core API overview

import Styletron from 'styletron'; // either styletron-server or styletron-client (package.json browser field)
const styletron = new Styletron();
styletron.injectDeclaration({prop: 'color', val: 'red'});
// → 'a'
styletron.injectDeclaration({prop: 'color', val: 'red', media: '(min-width: 800px)'});
// → 'b'
styletron.injectDeclaration({prop: 'color', val: 'blue'});
// → 'c'

Injecting style objects

The styletron-utils packages includes some convenient helper functions that make working with the core API easier.

import {injectStyle} from 'styletron-utils';
injectStyle(styletron, {
  color: 'red',
  display: 'inline-block'
});
// → 'a d'
injectStyle(styletron, {
  color: 'red',
  fontSize: '1.6em'
});
// → 'a e'

Pseudo classes and media queries

The object literal syntax supported by styletron-utils also supports pseudo classes and media queries. This syntax is also supported in the styletron-react package.

injectStyle(styletron, {
  fontSize: '36px',
  '@media (max-width: 768px)': {
    fontSize: '24px'
  },
  ':hover': {
    backgroundColor: 'papayawhip'
  }
});

Full API documentation for Styletron is available at http://styletron.js.org

Using Styletron with React

Live Demo

The styletron-react package provides a convenient way to use Styletron in React applications. The API is inspired by the wonderful styled-components library, except with style objects instead of template strings.

Note: this is just one high-level interface, many others are possible with Styletron.

Creating styled element components

Static styles

import {styled} from 'styletron-react';

const Panel = styled('div', {
  backgroundColor: 'lightblue',
  fontSize: '12px'
});

<Panel>Hello World</Panel>

Using props and context in styles

import {styled} from 'styletron-react';

const Panel = styled('div', (props) => ({
  backgroundColor: props.alert ? 'orange' : 'lightblue',
  fontSize: '12px'
}));

<Panel alert>Danger!</Panel>

Extending other styled element components

import {styled} from 'styletron-react';

const DeluxePanel = styled(Panel, (props) => ({
  backgroundColor: props.alert ? 'firebrick' : 'rebeccapurple',
  color: 'white',
  boxShadow: '3px 3px 3px darkgray'
}));

<DeluxePanel>Bonjour Monde</DeluxePanel>

Styling third party components

import {styled} from 'styletron-react';

// third party components must consume a `className` prop
const ThirdParty = ({className, href, children}) =>
  <a className={className} href={href}>{children}</a>

const StyledThirdParty = styled(ThirdParty, (props) => ({
  color: 'gold'
}));

<StyledThirdParty href="/foo">Foo</StyledThirdParty>

App integration and server-side rendering

Server-side rendering

import Styletron from 'styletron-server';
import {StyletronProvider} from 'styletron-react';

function render() {
  const styletron = new Styletron();
  const appMarkup = ReactDOM.renderToString(
    <StyletronProvider styletron={styletron}>
      <App/>
    </StyletronProvider>
  );

  const stylesForHead = styletron.getStylesheetsHtml();
  
  return `<html><head>${stylesForHead}</head><body>${appMarkup}</body></html>`;
}

Client-side rendering w/ hydration

import Styletron from 'styletron-client';
import {StyletronProvider} from 'styletron-react';

const styleElements = document.getElementsByClassName('_styletron_hydrate_');

ReactDOM.render(
  <StyletronProvider styletron={new Styletron(styleElements)}>
    <App/>
  </StyletronProvider>,
  document.getElementById('app')
);

Client-side rendering only

import Styletron from 'styletron-client';
import {StyletronProvider} from 'styletron-react';

ReactDOM.render(
  <StyletronProvider styletron={new Styletron()}>
    <App/>
  </StyletronProvider>,
  document.getElementById('app')
);

Earlo/styletron