styled-components

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

weekly downloads7.8M

versionv6.3.10

licenseMIT

categorystyling

reactcsscss-in-jsstyled-componentsstyling

Overview

styled-components is a CSS-in-JS library that uses tagged template literals to write actual CSS syntax within JavaScript files, binding styles directly to React components. Instead of maintaining separate CSS files and worrying about class name collisions, you create styled components that encapsulate both structure and presentation. The library generates unique class names automatically and injects only the critical CSS needed for rendered components.

The package emerged from the need to solve CSS's global namespace problem in component-based architectures. Traditional CSS requires careful management of specificity and naming conventions (like BEM) to avoid conflicts. styled-components eliminates this by scoping styles at the component level while maintaining the full power of CSS, including pseudo-selectors, media queries, and keyframe animations.

With over 7.7 million weekly downloads, styled-components has become one of the most widely adopted styling solutions in the React ecosystem. It's used in production by companies building design systems, large-scale applications, and component libraries where style isolation and dynamic theming are critical. The library works with both React DOM and React Native, making it suitable for cross-platform development.

Version 6.x brings improved TypeScript support, better performance through enhanced caching, and reduced bundle size. The library integrates seamlessly with modern build tools and supports server-side rendering out of the box, making it viable for SEO-critical applications and Next.js projects.

Quick Start

typescript

import styled, { ThemeProvider } from 'styled-components';
import { useState } from 'react';

const theme = {
  colors: {
    primary: '#0070f3',
    danger: '#e00',
    text: '#333'
  },
  spacing: (n) => `${n * 8}px`
};

const Button = styled.button`
  padding: ${props => props.theme.spacing(2)} ${props => props.theme.spacing(3)};
  background: ${props => props.variant === 'danger' 
    ? props.theme.colors.danger 
    : props.theme.colors.primary};
  color: white;
  border: none;
  border-radius: 4px;
  font-size: 16px;
  cursor: pointer;
  transition: opacity 0.2s;
  
  &:hover {
    opacity: 0.8;
  }
  
  &:disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }
`;

const Card = styled.div`
  padding: ${props => props.theme.spacing(3)};
  border: 1px solid #ddd;
  border-radius: 8px;
  
  ${Button} {
    margin-top: ${props => props.theme.spacing(2)};
  }
  
  @media (max-width: 768px) {
    padding: ${props => props.theme.spacing(2)};
  }
`;

function App() {
  const [loading, setLoading] = useState(false);
  
  const handleClick = () => {
    setLoading(true);
    setTimeout(() => setLoading(false), 2000);
  };
  
  return (
    <ThemeProvider theme={theme}>
      <Card>
        <h2>Styled Component Example</h2>
        <Button onClick={handleClick} disabled={loading}>
          {loading ? 'Loading...' : 'Click Me'}
        </Button>
        <Button variant="danger" onClick={() => alert('Danger!')}>
          Delete
        </Button>
      </Card>
    </ThemeProvider>
  );
}

export default App;

Use Cases

Component Libraries and Design Systems: Building reusable UI components that need self-contained styles without external CSS dependencies. Each component can export its styled variants, making distribution through npm straightforward without worrying about CSS file imports or class name conflicts across consuming applications.

Dynamic Theming Applications: Apps requiring runtime theme switching (dark mode, user-customizable themes, white-labeling). The ThemeProvider allows passing theme objects down the component tree, enabling components to access theme values and recalculate styles without page reloads or CSS variable limitations in older browsers.

Conditional Styling Based on Props: Complex UI components where visual appearance depends on state, user interaction, or data values. Instead of managing multiple className combinations or inline style objects, you can write CSS that directly references component props, making the relationship between state and presentation explicit.

Responsive Components with Complex Logic: Building components that need different styles at various breakpoints with logic that JavaScript can express better than CSS alone. You can compute breakpoints, combine media queries with prop-based conditions, and create responsive behavior that depends on runtime data.

Migrating Legacy Inline Styles: Gradually refactoring React codebases that use inline style objects by converting them to styled-components while maintaining the same prop-based styling patterns. The library accepts both template literals and object notation, enabling incremental migration without rewriting entire components.

Pros & Cons

Pros

+Automatic critical CSS injection means only styles for rendered components are added to the DOM, improving initial load performance compared to large global stylesheets
+True CSS syntax support including pseudo-selectors, media queries, and animations without learning a new DSL or dealing with JavaScript object limitations
+Eliminates class naming concerns entirely through automatic unique class generation, making it impossible to have style collisions across components
+Props-based dynamic styling is more intuitive than className manipulation, especially for components with multiple conditional style variations
+Strong TypeScript support in v6+ with proper prop type inference and theme typing, catching style-related errors at compile time

Cons

−Runtime performance overhead from parsing CSS template literals and injecting styles, though usually negligible, can impact components that re-render extremely frequently
−Debugging can be harder with auto-generated class names in production (though the Babel plugin helps), making browser DevTools inspection less intuitive than semantic class names
−Increases JavaScript bundle size since all styles ship as JS code, whereas traditional CSS can be cached separately and loaded in parallel
−Learning curve for developers accustomed to traditional CSS workflows, particularly around component selector patterns and theme provider setup
−Server-side rendering requires additional configuration and the Babel plugin to avoid hydration mismatches and ensure consistent class name generation

Alternatives

@vanilla-extract/cssv1.18.0

Zero-runtime Stylesheets-in-TypeScript

styling

1.3M / week

Comparisons

tailwindcss vs styled-components

styling

styled-components vs @emotion/react

styling

Install

bash

npm install styled-components

bash

pnpm add styled-components

bash

bun add styled-components

Overview

Quick Start

typescript

import styled, { ThemeProvider } from 'styled-components';
import { useState } from 'react';

const theme = {
  colors: {
    primary: '#0070f3',
    danger: '#e00',
    text: '#333'
  },
  spacing: (n) => `${n * 8}px`
};

const Button = styled.button`
  padding: ${props => props.theme.spacing(2)} ${props => props.theme.spacing(3)};
  background: ${props => props.variant === 'danger' 
    ? props.theme.colors.danger 
    : props.theme.colors.primary};
  color: white;
  border: none;
  border-radius: 4px;
  font-size: 16px;
  cursor: pointer;
  transition: opacity 0.2s;
  
  &:hover {
    opacity: 0.8;
  }
  
  &:disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }
`;

const Card = styled.div`
  padding: ${props => props.theme.spacing(3)};
  border: 1px solid #ddd;
  border-radius: 8px;
  
  ${Button} {
    margin-top: ${props => props.theme.spacing(2)};
  }
  
  @media (max-width: 768px) {
    padding: ${props => props.theme.spacing(2)};
  }
`;

function App() {
  const [loading, setLoading] = useState(false);
  
  const handleClick = () => {
    setLoading(true);
    setTimeout(() => setLoading(false), 2000);
  };
  
  return (
    <ThemeProvider theme={theme}>
      <Card>
        <h2>Styled Component Example</h2>
        <Button onClick={handleClick} disabled={loading}>
          {loading ? 'Loading...' : 'Click Me'}
        </Button>
        <Button variant="danger" onClick={() => alert('Danger!')}>
          Delete
        </Button>
      </Card>
    </ThemeProvider>
  );
}

export default App;

Use Cases

Pros & Cons

Pros

+Automatic critical CSS injection means only styles for rendered components are added to the DOM, improving initial load performance compared to large global stylesheets
+True CSS syntax support including pseudo-selectors, media queries, and animations without learning a new DSL or dealing with JavaScript object limitations
+Eliminates class naming concerns entirely through automatic unique class generation, making it impossible to have style collisions across components
+Props-based dynamic styling is more intuitive than className manipulation, especially for components with multiple conditional style variations
+Strong TypeScript support in v6+ with proper prop type inference and theme typing, catching style-related errors at compile time

Cons

−Runtime performance overhead from parsing CSS template literals and injecting styles, though usually negligible, can impact components that re-render extremely frequently
−Debugging can be harder with auto-generated class names in production (though the Babel plugin helps), making browser DevTools inspection less intuitive than semantic class names
−Increases JavaScript bundle size since all styles ship as JS code, whereas traditional CSS can be cached separately and loaded in parallel
−Learning curve for developers accustomed to traditional CSS workflows, particularly around component selector patterns and theme provider setup
−Server-side rendering requires additional configuration and the Babel plugin to avoid hydration mismatches and ensure consistent class name generation