Linaria — Zero-Runtime CSS-in-JS for React and Beyond

Introduction

Linaria is a zero-runtime CSS-in-JS library that lets developers write styles using tagged template literals in JavaScript or TypeScript. At build time, Linaria extracts all styles into static .css files and replaces the runtime calls with class name references, eliminating the JavaScript overhead that traditional CSS-in-JS libraries impose on every page load.

What Linaria Does

• Extracts CSS from tagged template literals into static .css files during the build step
• Provides a styled API similar to styled-components for creating React components with scoped styles
• Supports dynamic styles through CSS custom properties instead of runtime style injection
• Works with Webpack, Vite, Rollup, and esbuild via dedicated plugins
• Generates unique, deterministic class names to prevent collisions

Architecture Overview

Linaria uses a Babel plugin (now part of the wyw-in-js toolchain) that evaluates tagged template literals at build time. The plugin runs a mini JavaScript interpreter to resolve interpolated values, then emits the resulting CSS into a separate file. The original JavaScript import is rewritten to reference the generated class name string. Dynamic values that depend on props are converted to CSS custom properties set via inline styles at runtime.

Self-Hosting and Configuration

• Add the Linaria Webpack loader, Vite plugin, or Rollup plugin to your bundler config
• Import css from @linaria/core and styled from @linaria/react in your components
• Configure evaluation rules in linaria.config.js for custom module resolution
• Use @linaria/babel-preset for Babel-based setups or the wyw-in-js transformer
• Source maps connect generated CSS back to the original JS file for debugging

Key Features

• Zero runtime: no JavaScript is shipped to the browser for style injection
• Full CSS support including media queries, pseudo-selectors, and keyframe animations
• TypeScript support with type-safe styled component props
• Server-side rendering works without special configuration since styles are static files
• Atomic CSS mode optionally deduplicates common declarations for smaller output

Comparison with Similar Tools

• styled-components — evaluates styles at runtime, adding a JS overhead; Linaria extracts at build time for zero runtime cost
• Emotion — similar runtime CSS-in-JS approach; Linaria offers the same DX with static extraction
• Vanilla Extract — also zero-runtime but uses object-style syntax instead of template literals
• Tailwind CSS — utility-first classes defined in HTML; Linaria keeps styles co-located with components in JS

FAQ

Q: Does Linaria work with Next.js? A: Yes. A Next.js plugin is available that integrates the wyw-in-js transformer into the build pipeline.

Q: How are dynamic props handled without a runtime? A: Linaria converts prop-dependent values into CSS custom properties and sets them via inline style attributes on the element.

Q: Can I use Linaria outside of React? A: Yes. The css tag from @linaria/core generates plain class names usable with any framework or vanilla HTML.

Q: Does it support theming? A: Theming works via CSS custom properties. Define theme tokens as custom properties on :root and reference them in your Linaria styles.

Sources

• https://github.com/callstack/linaria
• https://linaria.dev/