⚡️ Toolkit for component-oriented styling
JavaScript
Switch branches/tags
v3.0.4 v3.0.3 v3.0.2 v3.0.1 v3.0.0 v3.0.0-rc.7 v3.0.0-rc.6 v3.0.0-rc.5 v3.0.0-rc.4 v3.0.0-rc.3 v3.0.0-rc.2 v3.0.0-rc.1 v2.5.10 v2.5.9 v2.5.8 v2.5.7 v2.5.6 v2.5.5 v2.5.4 v2.5.4-devtools.0 v2.5.3 v2.5.2 v2.5.1 v2.5.0 v2.4.0 v2.3.0 v2.2.1 v2.2.0 v2.1.2 v2.1.1 v2.1.0 v2.0.5 v2.0.4 v2.0.3 v2.0.2 v2.0.2-beta.3 v2.0.2-beta.2 v2.0.2-beta.1 v2.0.2-beta.0 v2.0.1 v2.0.1-beta.4 v2.0.1-beta.3 v2.0.1-beta.2 v2.0.1-beta.1 v2.0.1-beta.0 v2.0.0 v2.0.0-beta.4 v2.0.0-beta.3 v2.0.0-beta.2 v2.0.0-beta.1 v2.0.0-beta.0 v1.0.2 v1.0.1 v1.0.0 v0.2.2 v0.2.1 v0.2.0 v0.1.1 styletron@2.0.1-beta.2 styletron@1.0.4 styletron@1.0.2 styletron-utils@2.0.1-beta.2 styletron-standard@1.0.6 styletron-standard@1.0.5 styletron-standard@1.0.4 styletron-standard@1.0.3 styletron-standard@1.0.2 styletron-standard@1.0.1 styletron-standard@1.0.0 styletron-standard@1.0.0-beta.7 styletron-standard@1.0.0-beta.6 styletron-standard@1.0.0-beta.4 styletron-standard@1.0.0-beta.3 styletron-standard@1.0.0-beta.2 styletron-standard@1.0.0-beta.1 styletron-standard@1.0.0-beta.0 styletron-server@2.0.1-beta.1 styletron-react@4.3.5 styletron-react@4.3.4 styletron-react@4.3.3 styletron-react@4.3.2 styletron-react@4.3.1 styletron-react@4.3.0 styletron-react@4.2.2 styletron-react@4.2.1 styletron-react@4.2.0 styletron-react@4.1.0 styletron-react@4.0.3 styletron-react@4.0.2 styletron-react@4.0.1 styletron-react@4.0.0 styletron-react@4.0.0-beta.7 styletron-react@4.0.0-beta.6 styletron-react@4.0.0-beta.4 styletron-react@4.0.0-beta.3 styletron-react@4.0.0-beta.2 styletron-react@4.0.0-beta.1 styletron-react@4.0.0-beta.0 styletron-react@2.0.1-beta.1 styletron-react-core@1.3.2
Nothing to show
Clone or download
Latest commit 850180b Aug 14, 2018

README.md

Styletron logo

build status

Toolkit for component-oriented styling

Looking for v3.x docs? | v3.x to v4.x migration guide

Packages

Design principles

  1. Component-oriented
    • Stateless, single-element styled components as base styling primitive
    • Prop interfaces for conditional/dynamic styling
  2. Embrace typed JavaScript
    • Composition of styles via (typed) JavaScript objects
    • No extra tooling (e.g. Webpack loaders, Babel plugins, etc.)
  3. Portability and flexibility
    • Portability of styled components across different rendering engines (e.g. atomic CSS)
    • Core implementation agnostic of shape of style objects

See docs/design.md for more details.

Getting Started

Defining styled components

import {styled} from "styletron-react";

// Create a styled component by passing an element name and a style object
const RedAnchor = styled("a", {color: "red"});

<RedAnchor href="/foo">Hello</RedAnchor>;

// Or pass a function that takes props and returns a style object
const Panel = styled("div", props => {
  return {backgroundColor: props.$alert ? "orange" : "lightblue"};
});

<Panel $alert>Hello!</Panel>;

See packages/styletron-react for full documentation

Composing styled components

styletron-react also provides composition helpers such as withStyle to build styled components from existing styled components.

import {withStyle} from "styletron-react";

const FancyAnchor = withStyle(RedAnchor, {fontFamily: "cursive"});

<FancyAnchor href="/foo">Hello</FancyAnchor>;

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

<DeluxePanel>Bonjour Monde</DeluxePanel>;

See packages/styletron-react for full documentation

Providing a rendering engine

Styled components require a rendering engine to perform side effects (such as rendering styles to the page).

import {Provider as StyletronProvider} from "styletron-react";
import {Client as Styletron} from "styletron-engine-atomic";

// 1. Create a client engine instance
const engine = new Styletron();

// 2. Provide the engine to the app
React.render(
  <StyletronProvider value={engine}>
    <App />
  </StyletronProvider>
);

Server-side rendering

Extracting server-rendered styles

import {Provider as StyletronProvider} from "styletron-react";
import {Server as Styletron} from "styletron-engine-atomic";

// 1. Create a server engine instance
const engine = new Styletron();

// 2. Provide the engine to the app
const html = React.render(
  <StyletronProvider value={engine}>
    <App />
  </StyletronProvider>
);

// 3. Extract critical styles after SSR
const styles = engine.getStyleSheetsHTML();
// → "<style ..."

Hydrating server-rendered styles

When server-side rendering, pass the server-rendered styled elements to the client engine constructor to hydrate the client-side cache. This prevents these styles from being re-rendered and avoids potential style conflicts.

import {Provider as StyletronProvider} from "styletron-react";
import {Client as Styletron} from "styletron-engine-atomic";

// create an engine instance
- const engine = new Styletron();
+ const engine = new Styletron({hydrate: document.getElementsByClassName("_styletron_hydrate_")});

// wrap root component with provider
React.render(
  <StyletronProvider value={engine}>
    <App/>
  </StyletronProvider>
);

See packages/styletron-engine-atomic for full documentation.

Tradeoffs

See TRADEOFFS.md