Linaria

Zero-runtime CSS in JS library

README

Linaria

Zero-runtime CSS in JS library.


[![Build Status][build-badge]][build] [![Code Coverage][coverage-badge]][coverage] [![Version][version-badge]][package] [![MIT License][license-badge]][license]
[![All Contributors][all-contributors-badge]](#contributors) [![PRs Welcome][prs-welcome-badge]][prs-welcome] [![Chat][chat-badge]][chat] [![Code of Conduct][coc-badge]][coc] [![Greenkeeper][greenkeeper-badge]][greenkeeper] [![Sponsored by Callstack][callstack-badge]][callstack]
[![tweet][tweet-badge]][tweet]

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
- Use JavaScript for logic, no CSS preprocessor needed
- Optionally use any CSS preprocessor such as Sass or PostCSS
- Supports atomic styles with @linaria/atomic


Installation


  1. ```sh
  2. npm install @linaria/core @linaria/react @linaria/babel-preset
  3. ```

or

  1. ```sh
  2. yarn add @linaria/core @linaria/react @linaria/babel-preset
  3. ```

Setup


Linaria currently supports webpack and Rollup to extract the CSS at build time. To configure your bundler, check the following guides:


Or configure Linaria with one of the following integrations:


Optionally, add the @linaria preset to your Babel configuration at the end of the presets list to avoid errors when importing the components in your server code or tests:

  1. ``` json
  2. {
  3.   "presets": [
  4.     "@babel/preset-env",
  5.     "@babel/preset-react",
  6.     "@linaria"
  7.   ]
  8. }
  9. ```

See Configuration to customize how Linaria processes your files.

Syntax


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

  1. ``` js
  2. import { css } from '@linaria/core';
  3. import { modularScale, hiDPI } from 'polished';
  4. import fonts from './fonts';

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

  10.   ${hiDPI(1.5)} {
  11.     font-size: ${modularScale(2.5)};
  12.   }
  13. `;

  14. // Then use it as a class name
  15. <h1 className={header}>Hello world</h1>;
  16. ```

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 thestyled helper, which makes it easy to write React components with dynamic styles with a styled-component like syntax:

  1. ``` js
  2. import { styled } from '@linaria/react';
  3. import { families, sizes } from './fonts';

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

  8. const Container = styled.div`
  9.   font-size: ${sizes.medium}px;
  10.   color: ${props => props.color};
  11.   border: 1px solid red;

  12.   &:hover {
  13.     border-color: blue;
  14.   }

  15.   ${Title} {
  16.     margin-bottom: 24px;
  17.   }
  18. `;

  19. // Then use the resulting component
  20. <Container color="#333">
  21.   <Title>Hello world</Title>
  22. </Container>;
  23. ```

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

See Basics for a detailed information about the syntax.

Demo

Edit Linaria Demo

Documentation


- [Dynamic styles with css tag](/docs/DYNAMIC_STYLES.md)
  - webpack
  - Rollup
- CLI

Contributing


We appreciate any support in library development!

Take a look on Contributing docs to check how you can run Linaria in development mode.

Trade-offs


- No IE11 support when using dynamic styles in components with styled, since it uses CSS custom properties
- Dynamic styles are not supported with css tag. See [Dynamic styles with css tag](/docs/DYNAMIC_STYLES.md) for alternative approaches.
- Modules used in the CSS rules cannot have side-effects.
  For example:

  1. ``` js
  2.   import { css } from '@linaria/core';
  3.   import colors from './colors';

  4.   const title = css`
  5.     color: ${colors.text};
  6.   `;
  7. ```

  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.

Interoperability with other CSS-in-JS libraries


Linaria can work together with other CSS-in-JS libraries out-of-the-box. However, if you want to use styled components from Linaria as selectors in styled-components/emotion, you need to use @linaria/interop

Editor Plugins


VSCode


- Syntax Highlighting - language-babel
- Autocompletion - vscode-styled-components
- Linting - stylelint

Atom


- Syntax Highlighting and Autocompletion - language-babel

Webstorm


- Syntax Highlighting & Autocompletion - webstorm-styled-components

Sublime Text


- Syntax Highlighting & Autocompletion - Naomi, JSCustom (refer to document on how to turn on Styled Component syntax)

Recommended Libraries


- gatsby-plugin-linaria – Gatsby plugin that sets up Babel and webpack configuration for Linaria.
- polished.js - A lightweight toolset for writing styles in JavaScript.
- craco-linaria - A Craco plugin that allows you to use Linaria without ejecting from a CRA.

Inspiration



Acknowledgements


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


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

Made with ❤️ at Callstack


Linaria is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. Callstack is a group of React and React Native geeks, contact us at hello@callstack.com if you need any help with these or just want to say hi!

Like the project? ⚛️ Join the team who does amazing stuff for clients and drives React Native Open Source! 🔥

Sponsors


{callstack}

Servers.com


Contributors


Thanks goes to these wonderful people (emoji key):




Paweł Trysła
Paweł Trysła

💻 📖 🤔
Satyajit Sahoo
Satyajit Sahoo

💻 📖 🤔
Michał Pierzchała
Michał Pierzchała

💻 📖 🤔
Lucas
Lucas

📖
Alexey Pronevich
Alexey Pronevich

📖
Wojtek Szafraniec
Wojtek Szafraniec

💻
Anton Evzhakov
Anton Evzhakov

💻 🤔 📖
Tushar Sonawane
Tushar Sonawane

📖 💡
Ferran Negre
Ferran Negre

📖
Jakub Beneš
Jakub Beneš

💻 📖
Oscar Busk
Oscar Busk

🐛 💻
Dawid
Dawid

💻 📖
Kacper Wiszczuk
Kacper Wiszczuk

💻 📖
Denis Rul
Denis Rul

💻
Johan Holmerin
Johan Holmerin

💻 📖
Gilad Peleg
Gilad Peleg

📖
Giuseppe
Giuseppe

💻
Matija Marohnić
Matija Marohnić

💻 📖
Stefan Schult
Stefan Schult

💻
Ward Peeters
Ward Peeters

💻
radoslaw-medryk
radoslaw-medryk

💻
杨兴洲
杨兴洲

💻
Dawid Karabin
Dawid Karabin

📖
Chris Abrams
Chris Abrams

💻 📖 🤔
Jayphen
Jayphen

💻
c4605
c4605

💻
Toru Kobayashi
Toru Kobayashi

💻
Jakub Mazurek
Jakub Mazurek

💻
Joshua Nelson
Joshua Nelson

💻 🤔 📖
Tomasz Krzyżowski
Tomasz Krzyżowski

💻
Martin Schulze
Martin Schulze

💻
wmzy
wmzy

💻
Hyeseong Kim
Hyeseong Kim

💻
Martin Hochel
Martin Hochel

💻
Daniel Lo Nigro
Daniel Lo Nigro

💻
0xflotus
0xflotus

💻
Afzal Sayed
Afzal Sayed

💻
AijiUejima
AijiUejima

💻
Oleksii Vasyliev
Oleksii Vasyliev

💻
Alican Erdoğan
Alican Erdoğan

💻
Aman Kubanychbek
Aman Kubanychbek

💻
Andrew Gerard
Andrew Gerard

💻
Andrey Frolov
Andrey Frolov

💻
Benjamin Solum
Benjamin Solum

💻
Billy Kwok
Billy Kwok

💻
Christian Todd
Christian Todd

💻
David Peek
David Peek

💻
Denis Skiba
Denis Skiba

💻
Dima Kharitonov
Dima Kharitonov

💻
Gabriel Valfridsson
Gabriel Valfridsson

💻
Gitai
Gitai

💻
Hampus Kraft
Hampus Kraft

💻
Igor Sukharev
Igor Sukharev

💻
Ikko Ashimine
Ikko Ashimine

💻
Iman Mohamadi
Iman Mohamadi

💻
JB <codecorsair>
JB

💻
Jack Works
Jack Works

💻
James George
James George

💻
Jed Mao
Jed Mao

💻
Joe Lencioni
Joe Lencioni

💻
Joey Cozza
Joey Cozza

💻
Juan Ferreras
Juan Ferreras

💻
Kazuma Ebina
Kazuma Ebina

💻
Lars Kappert
Lars Kappert

💻
Luciano Mammino
Luciano Mammino

💻
Madhav Varshney
Madhav Varshney

💻
Malash
Malash

💻
Martijn Swaagman
Martijn Swaagman

💻
Matias Lahti
Matias Lahti

💻
Michael James
Michael James

💻
Michael Strobel
Michael Strobel

💻
Michał Chudziak
Michał Chudziak

💻
Mike
Mike

💻
Mike Stop Continues
Mike Stop Continues

💻
Mokshit Jain
Mokshit Jain

💻
Oleksandr Fediashov
Oleksandr Fediashov

💻
Paddy O'Brien
Paddy O'Brien

💻
Patrik Smělý
Patrik Smělý

💻
Pavel Udaloff
Pavel Udaloff

💻
Przemysław Bitkowski
Przemysław Bitkowski

💻
RiN
RiN

💻
Roman Sokhan
Roman Sokhan

💻
Seokmin Hong (Ray)
Seokmin Hong (Ray)

💻
Serge K Lebedev
Serge K Lebedev

💻
Sergey Korovin
Sergey Korovin

💻
Shreyas Sreenivas
Shreyas Sreenivas

💻
Sky Wickenden
Sky Wickenden

💻
Stanislav Panferov
Stanislav Panferov

💻
Ted Jenkins
Ted Jenkins

💻
Thanh Tran
Thanh Tran

💻
Thor Amorim
Thor Amorim

💻
tobenna
tobenna

💻
Tomas Carnecky
Tomas Carnecky

💻
Tsubasa1218
Tsubasa1218

💻
Turadg Aleahmad
Turadg Aleahmad

💻
Vitor Buzinaro
Vitor Buzinaro

💻
Mistereo
Mistereo

💻
Vladislav Kozulya
Vladislav Kozulya

💻
Yuhei Yasuda
Yuhei Yasuda

💻
Danil Kamyshov
Danil Kamyshov

💻
Sebastian Landwehr
Sebastian Landwehr

💻
everdimension
everdimension

💻
ptol
ptol

💻
roottool
roottool

💻
ryamaguchi0220
ryamaguchi0220

💻
simka
simka

💻
soso
soso

💻
Nikita Skovoroda
Nikita Skovoroda

💻
黄小健
黄小健

💻
iMoses
iMoses

💻
Jeremy Neander
Jeremy Neander

💻
Andy Parsons
Andy Parsons

💻
Platane
Platane

📖
Tim Kutnick
Tim Kutnick

📖






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



[build-badge]: https://img.shields.io/circleci/project/github/callstack/linaria/master.svg?style=flat-square
[build]: https://circleci.com/gh/callstack/linaria
[coverage-badge]: https://img.shields.io/codecov/c/github/callstack/linaria.svg?style=flat-square
[coverage]: https://codecov.io/github/callstack/linaria
[version-badge]: https://img.shields.io/npm/v/linaria.svg?style=flat-square
[package]: https://www.npmjs.com/package/linaria
[license-badge]: https://img.shields.io/npm/l/linaria.svg?style=flat-square
[license]: https://opensource.org/licenses/MIT
[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
[prs-welcome]: https://github.com/callstack/linaria/blob/master/CONTRIBUTING.md
[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
[coc]: https://github.com/callstack/linaria/blob/master/CODE_OF_CONDUCT.md
[all-contributors-badge]: https://img.shields.io/badge/all_contributors-23-orange.svg?style=flat-square
[chat-badge]: https://img.shields.io/discord/426714625279524876.svg?style=flat-square&colorB=758ED3
[chat]: https://discord.gg/zwR2Cdh
[tweet-badge]: https://img.shields.io/badge/tweet-%23linaria-blue.svg?style=flat-square&colorB=1DA1F2&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAUCAYAAACXtf2DAAAAAXNSR0IArs4c6QAAAaRJREFUOBGtlM8rBGEYx3cWtRHJRaKcuMtBSitxkCQ3LtzkP9iUUu5ODspRHLhRLtq0FxeicEBC2cOivcge%2FMgan3fNM8bbzL4zm6c%2BPT%2Fe7%2FO8887svrFYBWbbtgWzsAt3sAcpqJFxxF1QV8oJFqFPFst5dLWQAT87oTgPB7DtziFRT1EA4yZolsFkhwjGYFRO8Op0KD8HVe7unoB6PRTBZG8IctAmG1xrHcfkQ2B55sfI%2ByGMXSBqV71xZ8CWdxBxN6ThFuECDEAL%2Bc9HIzDYumVZ966GZnX0SzCZvEqTbkaGywkyFE6hKAsBPhFQ18uPUqh2ggJ%2BUor%2F4M%2F%2FzOC8g6YzR1i%2F8g4vvSI%2ByD7FFNjexQrjHd8%2BnjABI3AU4Wl16TuF1qANGll81jsi5qu%2Bw6XIsCn4ijhU5FmCJpkV6BGNw410hfSf6JKBQ%2FUFxHGYBnWnmOwDwYQ%2BwzdHqO75HtiAMJfaC7ph32FSRJCENUhDHsLaJkL%2FX4wMF4%2BwA5bgAcrZE4sr0Cu9Jq9fxyrvBHWbNkMD5CEHWTjjT2m6r5D92jfmbbKJEWuMMAAAAABJRU5ErkJggg%3D%3D
[tweet]: https://twitter.com/intent/tweet?text=Check%20out%20linaria!%20https://github.com/callstack/linaria%20%F0%9F%91%8D
[greenkeeper-badge]: https://badges.greenkeeper.io/callstack/linaria.svg
[greenkeeper]: https://greenkeeper.io/
[callstack-badge]: https://callstack.com/images/callstack-badge.svg
[callstack]: https://callstack.com/open-source/?utm_source=github.com&utm_medium=referral&utm_campaign=linaria&utm_term=readme