JSPM

Zero-runtime CSS in JS library.

Features

• Write CSS in JS, but with zero runtime, CSS is extracted to CSS files during build
• Familiar CSS syntax with Sass like nesting
• Use dynamic prop based styles with the React bindings, uses CSS variables behind the scenes
• Easily find where the style was defined with CSS sourcemaps
• Lint your CSS in JS with stylelint

Why use Linaria

Usage

Linaria requires you to use a babel plugin along with a webpack loader.

First, add the babel preset to your .babelrc:

{
  "presets": [
    "@babel/preset-env",
    "@babel/preset-react",
    "linaria/babel"
  ]
}

Make sure that linaria/babel is the last item in your presets list.

Next, add the webpack loader to your webpack.config.js:

module: {
  rules: [
    {
      test: /\.js$/,
      use: [
        {
          loader: 'linaria/loader',
          options: {
            sourceMap: process.env.NODE_ENV !== 'production',
          },
        },
        {
          loader: 'babel-loader'
        }
      ],
    },
    {
      test: /\.css$/,
      use: [
        MiniCssExtractPlugin.loader,
        {
          loader: 'css-loader',
          options: {
            sourceMap: process.env.NODE_ENV !== 'production',
          },
        },
      ],
    },
  ],
  plugins: [
    new MiniCssExtractPlugin({
      filename: 'styles.css',
    }),
  ],
},

Make sure that linaria/loader is included before babel-loader.

Now, the CSS you write with Linaria will be extracted at build time to the styles.css file.

Syntax

Linaria can be used with any framework, with additional helpers for react. The basic syntax looks like this:

import { css } from 'linaria';
import { modularScale, hiDPI } from 'polished';
import fonts from './fonts';
import colors from './colors';

// Write your styles in `css` tag
const header = css`
  text-transform: uppercase;
  font-family: ${fonts.heading};
  font-size: ${modularScale(2)};

  ${hiDPI(1.5)} {
    font-size: ${modularScale(2.5)}
  }
`;

// Then use it as a class name
<h1 class={header}>Hello world</h1>

You can use imported variables and functions for logic inside the CSS code. They will be evaluated at build time.

If you're using React, you can use the styled helper, which makes it easy to write React components with dynamic styles with a styled-component like syntax:

import { styled } from 'linaria/react';
import { families, sizes } from './fonts';

const background = 'yellow';

// Write your styles in `styled` tag
const Title = styled.h1`
  font-family: ${families.serif};
`;

const Container = styled.div`
  font-size: ${sizes.medium}px;
  background-color: ${background};
  color: ${props => props.color};
  width: ${100 / 3}%;
  border: 1px solid red;

  &:hover {
    border-color: blue;
  }

  ${Title} {
    margin-bottom: 24px;
  }
`;

// Then use the resulting component
<Container color="#333">
  <Title>Hello world</Title>
</Container>

Dynamic styles will be applied using CSS custom properties (aka CSS variables) and don't require any runtime.

Documentation

• API and usage
  • Client APIs
  • Server APIs
• Configuring Babel
• Dynamic styles with css tag
• Theming
• Server rendering
• Bundlers integration
  • Webpack
• Linting
• How it works
• Example

Trade-offs

• No IE11 support when using dynamic styles components since it uses CSS custom properties

• The cascade is still there.

  For example, the following code can produce a div with color: red; or color: blue; depending on generated the order of CSS rules:

  // First.js
  import { styled } from 'linaria/react';
  
  const First = styled.div`
    color: blue;
  `;
  
  // Second.js
  import { styled } from 'linaria/react';
  import { First } from './First';
  
  const Second = styled(First)`
    color: red;
  `;

  Libraries like styled-components can get around the cascade because they can control the order of the CSS insertion during the runtime. It's not possible when statically extracting the CSS at build time.

• Dynamic styles are not supported with css tag. See Dynamic Styles for alternative approaches.

• Modules used in the CSS rules cannot have side-effects. For example:

  import { css } from 'linaria';
  import colors from './colors';
  
  const title = css`
    color: ${colors.text};
  `;

  Here, there should be no side-effects in the colors.js file, or any file it imports. We recommend to move helpers and shared configuration to files without any side-effects.

Editor Plugins

VSCode

• Syntax Highlighting - Styled Components Plugin
• Autocompletion - Styled Components Plugin

Atom

• Syntax Highlighting - Babel Grammar

Recommended Libraries

• linaria-jest – Jest testing utilities for Linaria.
• babel-plugin-object-styles-to-template - Babel plugin to write styles in object syntax with linaria
• polished.js - A lightweight toolset for writing styles in JavaScript.

Inspiration

• glam
• styled-components
• css-literal-loader

Acknowledgements

This project wouldn't have been possible without the following libraries or the people behind them.

• babel
• stylis.js

Special thanks to @kentcdodds for his babel plugin and @threepointone for his suggestions and encouragement.

Contributors

Thanks goes to these wonderful people (emoji key):

Paweł Trysła 💻 📖 🤔	Satyajit Sahoo 💻 🤔	Michał Pierzchała 💻 📖 🤔	Lucas 📖	Alexey Pronevich 📖	Wojtek Szafraniec 💻	Tushar Sonawane 📖 💡
Ferran Negre 📖	Jakub Beneš 💻 📖	Oscar Busk 🐛 💻	Dawid 💻 📖

This project follows the all-contributors specification. Contributions of any kind welcome!