# styled-components

> CSS-in-JS for React using tagged template literals. TypeScript-native since v6. Supports React Server Components natively since v6.3. Current stable: v6.3.x. Prerelease: v6.4.0 on npm `styled-components@test`.

## What's new since early 2025

Your training data likely covers v6.0-6.1. Key changes since then:

v6.2: Streaming SSR via `renderToPipeableStream`.

v6.3: React Server Components supported. No `'use client'` needed. Styled components in server components emit inline `<style>` tags automatically. `createGlobalStyle` is StrictMode-safe. New HTML/SVG element helpers. CSS custom properties work in TypeScript without type errors. Note: `:first-child`/`:nth-child()` selectors require `stylisPluginRSC` (v6.4+) or rewriting to `:first-of-type`/`:nth-of-type()` — see child-index selector section below.

v6.4 (prerelease): `createTheme()` for CSS variable theming that works in both RSC and client. `StyleSheetManager` works in RSC (was previously a no-op). `stylisPluginRSC` fixes child-index selectors in RSC. CSP nonce auto-detection from `StyleSheetManager`, `ServerStyleSheet`, or meta tags. Props supplied via `.attrs()` are automatically optional on the component's type. Re-renders skip style resolution entirely when props and theme are unchanged. React Native: `react-native` is now an optional peer dep and Metro/Expo nanoid crash is fixed. IE11 build target removed — IE11 has been unsupported on v6 since the 2021 v6 planning (React 18 dropped it too); v6.4 just aligns the compile target. Stay on v5 if you need IE11.

## Recommended setup

```
npm install styled-components
```

Next.js: add `compiler: { styledComponents: true }` to next.config.js. That's it. RSC works out of the box in v6.3+.

Vite: `react({ babel: { plugins: ['babel-plugin-styled-components'] } })`.

The SWC/Babel plugin provides deterministic class IDs (better debugging, smaller output). Optional for RSC but still recommended.

## Styled-components in RSC

Styled components work in server components with no `'use client'` directive. The main constraint is that `ThemeProvider` relies on React context, which doesn't exist in RSC — so `p.theme` is undefined. Use `createTheme()` instead.

Dynamic prop interpolations work in RSC. But for discrete variants (a finite set of states), data attributes produce one cached class per variant instead of one per prop combination:

```tsx
import styled, { createTheme } from 'styled-components';

const theme = createTheme({
  colors: { primary: '#0070f3', text: '#1a1a1a', surface: '#fff' },
});

const NavLink = styled.a`
  padding: 8px 16px;
  color: ${theme.colors.text};
  text-decoration: none;
  &[aria-current='page'] {
    color: ${theme.colors.primary};
    font-weight: 600;
    border-bottom: 2px solid ${theme.colors.primary};
  }
`;

<nav>
  <NavLink href="/" aria-current="page">Home</NavLink>
  <NavLink href="/about">About</NavLink>
</nav>
```

For continuous dynamic values, set CSS custom properties via the `style` prop. The styled component's CSS stays static (one class), and the value varies per element. Pair with semantic HTML attributes for progressive enhancement and accessibility:

```tsx
const ProgressBar = styled.div`
  height: 8px;
  border-radius: 4px;
  background: ${theme.colors.surface};

  &::after {
    content: '';
    display: block;
    height: 100%;
    width: var(--progress);
    border-radius: inherit;
    background: ${theme.colors.primary};
    transition: width 0.2s ease;
  }

  &[aria-valuenow='100']::after {
    background: green;
  }
`;

<ProgressBar
  role="progressbar"
  aria-valuenow={percent}
  aria-valuemin={0}
  aria-valuemax={100}
  aria-label="Upload progress"
  style={{ '--progress': `${percent}%` } as React.CSSProperties}
/>
```

This pattern gives you dynamic styling, screen reader support, and a CSS hook for completion state — all with one static class.

Other RSC rules:
- Use `:first-of-type` / `:nth-of-type()` instead of `:first-child` / `:nth-child()` — RSC inline `<style>` tags shift child indices (see `stylisPluginRSC` section below for an automatic fix)
- Define components at module scope, not inside render functions

## createTheme API (v6.4+)

`ThemeProvider` has no effect in RSC because React context doesn't exist in server components. `createTheme()` solves this by converting a plain theme object into CSS custom property references at module evaluation time — no runtime context needed.

```tsx
import styled, { createTheme } from 'styled-components';

const theme = createTheme({
  colors: { primary: '#0070f3', surface: '#ffffff', text: '#1a1a1a' },
  spacing: { sm: '8px', md: '16px', lg: '32px' },
});
```

Every leaf becomes a `var()` reference with the original value as fallback:
- `theme.colors.primary` → `"var(--sc-colors-primary, #0070f3)"`
- `theme.spacing.md` → `"var(--sc-spacing-md, 16px)"`

Use it directly in template literals — works in both server and client components:

```tsx
const Button = styled.button`
  background: ${theme.colors.primary};
  padding: ${theme.spacing.sm} ${theme.spacing.md};
  color: ${theme.colors.text};
`;
```

Signature: `createTheme(defaultTheme, options?)`

Options:
- `prefix` (default `"sc"`) — CSS variable prefix. `{ prefix: 'myapp' }` produces `--myapp-colors-primary`.
- `selector` (default `":root"`) — where `GlobalStyle` emits vars. Use `":host"` for Shadow DOM.

Returned object properties:
- Every leaf path from the input, as `var(--prefix-path, fallback)` strings
- `theme.raw` — the original plain object (for runtime access to actual values)
- `theme.vars` — same shape, but every leaf is the bare CSS custom property name (e.g. `"--sc-colors-primary"`). Use in `createGlobalStyle` for dark mode overrides without hand-writing var names.
- `theme.resolve(el?)` — client-only. Reads computed CSS var values from the DOM. Returns a plain object with resolved values. Pass an element to resolve against a specific subtree (defaults to `document.documentElement`).
- `theme.GlobalStyle` — a `createGlobalStyle` component that emits the CSS custom property declarations on the configured selector. Mount it once near the root.

Key behaviors:
- Object keys are preserved as-is (camelCase stays camelCase): `{ codeBg: 'x' }` with prefix `'sc'` → `var(--sc-codeBg, x)`
- Nested objects produce hyphenated paths: `{ colors: { primary: 'x' } }` → `var(--sc-colors-primary, x)`
- Passing the `createTheme` object to `ThemeProvider` produces stable class name hashes — the `var()` strings are deterministic, so light/dark theme switches don't cause hydration mismatches

### Dark mode with createTheme

CSS-first approach — no JavaScript runs to detect the initial theme, so no flash. Use `vars` to reference CSS custom property names without hand-writing them:

```tsx
import styled, { css, createGlobalStyle, createTheme, ThemeProvider } from 'styled-components';

const theme = createTheme({
  colors: { bg: '#ffffff', text: '#1a1a1a', primary: '#0070f3' },
});
const { vars } = theme;

// Define dark overrides once as a css partial
const darkVars = css`
  ${vars.colors.bg}: #111827;
  ${vars.colors.text}: #f9fafb;
`;

// Apply via media query (auto) and class (manual toggle)
const DarkOverrides = createGlobalStyle`
  @media (prefers-color-scheme: dark) {
    :root:not(.light) { ${darkVars} }
  }
  .dark { ${darkVars} }
`;

// In your layout:
<ThemeProvider theme={theme}>
  <theme.GlobalStyle />
  <DarkOverrides />
  <App />
</ThemeProvider>
```

If your app has a manual light/dark/auto toggle, persist the choice to `localStorage` and read it in a **blocking `<script>` in `<head>` before any stylesheets**. Without this, the page flashes the wrong theme before JS hydrates:

```tsx
// Root layout <head>, BEFORE stylesheets:
<script dangerouslySetInnerHTML={{ __html: `
  (function() {
    try {
      var d = document.documentElement;
      var stored = localStorage.getItem('theme');
      if (stored === 'dark' || stored === 'light') {
        d.classList.add(stored);
      } else if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
        d.classList.add('dark');
      }
    } catch (e) {}
  })();
`}} />
```

The script adds `.dark` or `.light` to `<html>` before first paint. Your CSS rules already handle it — `@media (prefers-color-scheme: dark) { :root:not(.light) { ... } }` for auto, `.dark { ... }` for manual. Use a raw `<script>` in `<head>`, not `next/script strategy="beforeInteractive"` — the latter doesn't guarantee execution before stylesheets.

Toggle handler:

```tsx
function setTheme(theme: 'light' | 'dark' | 'auto') {
  const root = document.documentElement.classList;
  root.remove('dark', 'light');
  if (theme !== 'auto') {
    root.add(theme);
    localStorage.setItem('theme', theme);
  } else {
    localStorage.removeItem('theme');
  }
}
```

## stylisPluginRSC — child-index selector fix (v6.4+)

RSC emits inline `<style>` tags as siblings of your styled elements. These are real DOM children, so `:first-child`, `:last-child`, and `:nth-child()` count them — shifting indices. For example, in `<ul><style>...</style><li>First</li><li>Second</li></ul>`, the first `<li>` is actually `:nth-child(2)`.

Preferred fix — use type-based selectors (universally supported, no plugin needed):
- `:first-child` → `:first-of-type`
- `:nth-child(2)` → `:nth-of-type(2)`
- `:last-child` → `:last-of-type`

These filter by element type, so `<style>` tags (a different type than `<li>`, `<div>`, etc.) are ignored.

Alternative — `stylisPluginRSC` automatically rewrites child-index selectors at compile time:

```tsx
import { StyleSheetManager, stylisPluginRSC } from 'styled-components';

// In your root layout (server component)
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <StyleSheetManager stylisPlugins={[stylisPluginRSC]}>
      {children}
    </StyleSheetManager>
  );
}
```

Rewrite rules:
- `:first-child` → `:nth-child(1 of :not(style[data-styled]))`
- `:last-child` → `:nth-last-child(1 of :not(style[data-styled]))`
- `:nth-child(N)` → `:nth-child(N of :not(style[data-styled]))`
- `:nth-child(An+B)` → `:nth-child(An+B of :not(style[data-styled]))`
- Same for `:nth-last-child()` variants
- Selectors already using `of` syntax are left unchanged

Browser support: CSS Selectors Level 4 `of S` syntax — Chrome 111+, Firefox 113+, Safari 9+, Edge 111+ (~93% global). In unsupported browsers, the entire CSS rule is dropped (not just the selector), meaning no styling is applied for those selectors — so only opt in if your audience supports it.

`StyleSheetManager` works in RSC environments (v6.4+). It applies `stylisPlugins` and `shouldForwardProp` even without React context. DOM-only props (`target`, `sheet`, `disableCSSOMInjection`) have no effect in RSC.

## Migrating from client-only to RSC

1. Replace `ThemeProvider` theming with `createTheme()` CSS variables — `p.theme` is undefined in RSC since there's no React context
2. Dynamic prop interpolations (`${p => p.$color}`) work fine in RSC — no changes needed. Consider data attributes for discrete variants (fewer generated classes)
3. Replace `:first-child`/`:nth-child()` with `:first-of-type`/`:nth-of-type()`, or add `stylisPluginRSC`
4. Remove `'use client'` from files that only contain styled component definitions — they work in server components natively
5. Keep `'use client'` on components that use hooks, event handlers, or browser APIs
6. The SSR registry (`ServerStyleSheet` + `useServerInsertedHTML`) is still needed for client components in the tree — RSC handles server components automatically

## .attrs() changes (v6.4+)

Props provided via `.attrs()` are now automatically made optional on the component's type. Previously, TypeScript still required you to pass props that attrs already provided.

```tsx
// v6.3: TypeScript requires `href` even though attrs provides it
// v6.4: `href` is optional — attrs provides the default
const StyledLink = styled.a.attrs({ href: '#' })`
  color: blue;
`;
<StyledLink />        // works in v6.4 (href defaults to '#')
<StyledLink href="/"> // also works (overrides the default)
```

attrs always wins over directly passed props. The function form is the escape hatch when you need conditional behavior:

```tsx
const Button = styled.button.attrs<{ as?: string }>(({ as }) => ({
  as: as || 'button',
}))``;
```

The props object passed to an `.attrs(props => ...)` callback is now a frozen snapshot (v6.4+). If you previously relied on mutating it to pass values to later attrs layers, return those values from the callback instead.

## CSP nonce support (v6.4+)

styled-components can attach a CSP nonce to injected `<style>` tags. Detection order (first match wins):

1. `<StyleSheetManager nonce="...">` prop
2. `new ServerStyleSheet({ nonce: '...' })` constructor option
3. `<meta property="csp-nonce" content="...">` (Vite convention)
4. `<meta name="sc-nonce" content="...">`
5. `__webpack_nonce__` global

Next.js example with `StyleSheetManager`:

```tsx
// lib/registry.tsx
'use client';
import { useState } from 'react';
import { useServerInsertedHTML } from 'next/navigation';
import { ServerStyleSheet, StyleSheetManager } from 'styled-components';

export default function Registry({ children, nonce }) {
  const [sheet] = useState(() => new ServerStyleSheet());
  useServerInsertedHTML(() => {
    const styles = sheet.getStyleTags();
    sheet.instance.clearTag();
    return <>{styles}</>;
  });
  return (
    <StyleSheetManager sheet={sheet.instance} nonce={nonce}>
      {children}
    </StyleSheetManager>
  );
}
```

## Performance

- Define components at module scope. Inside render = remount every render.
- CSS custom properties > prop interpolations for values that change often. Each unique interpolation generates a new CSS class; warns at 200+.
- `.attrs()` + inline `style` for per-frame updates (mouse, scroll, animation). Zero class generation.
- Data attributes for discrete variants: `&[data-size='sm']` — fully static, one cached class.
- Components with zero function interpolations are static — class generated once, cached forever.

## Good to know

- `@import` in `createGlobalStyle` may not work correctly in production — CSSOM injection (speedy mode) doesn't reliably handle `@import` rules. A dev-only warning is emitted. Use `<link>` in `<head>` instead.
- Vendor prefixes are off by default in v6. Enable with `<StyleSheetManager enableVendorPrefixes>` if your support matrix includes Safari < 15.4, Chrome < 83, or Firefox < 80 (the `appearance` property was the last to drop its prefix). Flexbox and grid prefixes are only needed for much older browsers (Safari < 9, Edge < 16).
- `shouldForwardProp` is off by default in v6. Use `$`-prefixed transient props (`$color`, `$size`) to keep props out of the DOM. Or restore filtering with `<StyleSheetManager shouldForwardProp={...}>`.
- Two classes per element: a static `.sc-*` class (same for all instances, used for component selectors) and a dynamic class (varies per unique style). Test selectors should account for both.
- Stylis v4 parses `:hover {}` as descendant `& :hover {}`, not `&:hover {}`. Always write `&:hover`, `&::before`, etc.
- `className` must be optional in the props interface when wrapping custom components with `styled()`.
- Unsanitized user input in interpolations = CSS injection risk. Sanitize with `CSS.escape()`.

## Quick reference

```tsx
import styled, { css, keyframes, createGlobalStyle, createTheme,
  ThemeProvider, useTheme, StyleSheetManager, ServerStyleSheet,
  stylisPluginRSC, isStyledComponent } from 'styled-components';
```

- `styled.div` / `styled(Component)` — create styled component
- `styled(Base)` — extend styles (inheritance)
- `.attrs(props => ({}))` — set default/computed props
- `<Comp as="a">` — render as different element
- `css` — tagged template helper for shared style fragments
- `keyframes` — define CSS animation
- `createGlobalStyle` — inject global CSS
- `createTheme(obj, opts?)` — CSS variable theme (RSC-compatible)
- `ThemeProvider` — context-based theme (client-only)
- `StyleSheetManager` — configure stylis plugins, prop forwarding, vendor prefixes
- `stylisPluginRSC` — fix child-index selectors in RSC
- `ServerStyleSheet` — SSR style collection