@emotion/react

> Simple styling in React.

weekly downloads13.4M

versionv11.14.0

licenseMIT

categorystyling

Overview

@emotion/react is a CSS-in-JS library designed specifically for React applications that allows developers to write styles directly alongside component logic. With over 13 million weekly downloads, it's one of the most popular styling solutions in the React ecosystem, powering production applications at companies ranging from startups to enterprises.

The library's core feature is the css prop, which enables inline styling without the overhead of creating separate styled components. You can write styles as JavaScript objects or template literals, leveraging the full power of JavaScript for dynamic, conditional, and computed styles. This approach eliminates the need for separate CSS files while maintaining component encapsulation and avoiding global namespace pollution.

@emotion/react provides first-class support for server-side rendering without additional configuration, automatic vendor prefixing for cross-browser compatibility, and built-in theming capabilities. The library generates styles at runtime only when needed, resulting in efficient bundle sizes and fast render performance. Its modular architecture allows you to use only what you need, and it integrates seamlessly with TypeScript for type-safe styling.

Developers choose @emotion/react when they want colocation of styles with components, need dynamic styling based on props or state, require SSR support, or prefer writing CSS in JavaScript rather than maintaining separate stylesheets. It's particularly well-suited for design systems, component libraries, and applications with complex theming requirements.

Quick Start

typescript

/** @jsxImportSource @emotion/react */
import { css, ThemeProvider, useTheme } from '@emotion/react';
import { useState } from 'react';

const theme = {
  colors: {
    primary: '#3b82f6',
    primaryHover: '#2563eb',
    text: '#1f2937',
    background: '#ffffff'
  },
  spacing: {
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem'
  }
};

function Button({ variant = 'primary', children }) {
  const theme = useTheme();
  const [isHovered, setIsHovered] = useState(false);

  return (
    <button
      css={css({
        padding: `${theme.spacing.sm} ${theme.spacing.lg}`,
        backgroundColor: isHovered ? theme.colors.primaryHover : theme.colors.primary,
        color: 'white',
        border: 'none',
        borderRadius: '0.375rem',
        fontSize: '0.875rem',
        fontWeight: 500,
        cursor: 'pointer',
        transition: 'background-color 0.2s',
        opacity: variant === 'disabled' ? 0.5 : 1,
        '&:active': {
          transform: 'scale(0.98)'
        },
        '@media (min-width: 768px)': {
          padding: `${theme.spacing.md} ${theme.spacing.lg}`,
          fontSize: '1rem'
        }
      })}
      onMouseEnter={() => setIsHovered(true)}
      onMouseLeave={() => setIsHovered(false)}
      disabled={variant === 'disabled'}
    >
      {children}
    </button>
  );
}

export default function App() {
  return (
    <ThemeProvider theme={theme}>
      <div css={css({
        padding: theme.spacing.lg,
        fontFamily: 'system-ui, sans-serif'
      })}>
        <Button>Click me</Button>
      </div>
    </ThemeProvider>
  );
}

Use Cases

Component-scoped styling: Apply styles directly to components without worrying about class name conflicts or global CSS pollution. Each component's styles are automatically scoped, making it ideal for large applications where multiple teams work on different features.

Dynamic theming: Build applications with switchable themes (light/dark mode, brand variations) by accessing theme values through React context. The theme object is available in all style declarations, enabling consistent design tokens across your application.

Conditional styling based on props: Style components dynamically based on props, state, or runtime conditions without creating multiple CSS classes. Compute styles using JavaScript logic, making it easy to implement variants, sizes, and states.

Server-side rendering: Deploy applications with SSR frameworks like Next.js or Remix where styles need to be extracted and injected during server rendering. @emotion/react handles critical CSS extraction automatically without additional build configuration.

Component libraries and design systems: Build reusable component libraries where styles are packaged with components. The css prop and styled API make it easy to expose style customization points while maintaining consistent defaults.

Pros & Cons

Pros

+Zero-config SSR support works out of the box with Next.js, Remix, and other frameworks
+Small bundle size and excellent runtime performance with incremental style injection
+Powerful css prop enables inline styling without creating wrapper components
+Built-in theming and TypeScript support with strong type inference
+Automatic vendor prefixing and nested selector support like Sass

Cons

−Runtime overhead compared to zero-runtime solutions like vanilla-extract or Linaria
−Requires JSX pragma or Babel configuration to use the css prop, adding setup complexity
−Styles defined in JavaScript may be harder to extract for static analysis tools
−Learning curve for developers accustomed to traditional CSS or CSS Modules
−Bundle size increases with application size since styles are JavaScript objects

Alternatives

styled-componentsv6.3.10

CSS for the <Component> Age. Style components your way with speed, strong typing, and flexibility.

stylingreactcss

7.8M / week

Comparisons

styled-components vs @emotion/react

styling

Install

bash

npm install @emotion/react

bash

pnpm add @emotion/react

bash

bun add @emotion/react

Overview

Quick Start

typescript

/** @jsxImportSource @emotion/react */
import { css, ThemeProvider, useTheme } from '@emotion/react';
import { useState } from 'react';

const theme = {
  colors: {
    primary: '#3b82f6',
    primaryHover: '#2563eb',
    text: '#1f2937',
    background: '#ffffff'
  },
  spacing: {
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem'
  }
};

function Button({ variant = 'primary', children }) {
  const theme = useTheme();
  const [isHovered, setIsHovered] = useState(false);

  return (
    <button
      css={css({
        padding: `${theme.spacing.sm} ${theme.spacing.lg}`,
        backgroundColor: isHovered ? theme.colors.primaryHover : theme.colors.primary,
        color: 'white',
        border: 'none',
        borderRadius: '0.375rem',
        fontSize: '0.875rem',
        fontWeight: 500,
        cursor: 'pointer',
        transition: 'background-color 0.2s',
        opacity: variant === 'disabled' ? 0.5 : 1,
        '&:active': {
          transform: 'scale(0.98)'
        },
        '@media (min-width: 768px)': {
          padding: `${theme.spacing.md} ${theme.spacing.lg}`,
          fontSize: '1rem'
        }
      })}
      onMouseEnter={() => setIsHovered(true)}
      onMouseLeave={() => setIsHovered(false)}
      disabled={variant === 'disabled'}
    >
      {children}
    </button>
  );
}

export default function App() {
  return (
    <ThemeProvider theme={theme}>
      <div css={css({
        padding: theme.spacing.lg,
        fontFamily: 'system-ui, sans-serif'
      })}>
        <Button>Click me</Button>
      </div>
    </ThemeProvider>
  );
}

Use Cases

Pros & Cons

Pros

+Zero-config SSR support works out of the box with Next.js, Remix, and other frameworks
+Small bundle size and excellent runtime performance with incremental style injection
+Powerful css prop enables inline styling without creating wrapper components
+Built-in theming and TypeScript support with strong type inference
+Automatic vendor prefixing and nested selector support like Sass

Cons

−Runtime overhead compared to zero-runtime solutions like vanilla-extract or Linaria
−Requires JSX pragma or Babel configuration to use the css prop, adding setup complexity
−Styles defined in JavaScript may be harder to extract for static analysis tools
−Learning curve for developers accustomed to traditional CSS or CSS Modules
−Bundle size increases with application size since styles are JavaScript objects