2nd/10_Wiki/Topics/Frontend/Styled Components v6.md

---
id: wiki-2026-0508-styled-components-v6
title: Styled Components v6
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [styled-components, sc-v6, CSS-in-JS]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [frontend, css-in-js, react, styled-components]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: react
---

# Styled Components v6

## 매 한 줄
> **"매 React-runtime CSS-in-JS 의 v6 modernization"**. 2023 release — stylis v4 (5x faster), `transient props` ($-prefix) 의 default, native `transient`, drop legacy babel-plugin in favor of SWC plugin. 2026 현재 RSC-incompatible 의 큰 단점 — Next.js App Router 사용 시 zero-runtime alternatives (Linaria/Vanilla Extract/Panda) 의 dominant.

## 매 핵심

### 매 v6 변경
- **stylis v4**: parser rewrite, 5x faster, smaller bundle.
- **`as` polymorphic prop**: typed properly with TS generics.
- **`$prop` transient**: forwarded to component but not DOM attr (was opt-in, now norm).
- **No babel-plugin needed**: SWC/Vite plugin 의 standard.
- **Drop**: `.extend`, primary-theme prop forwarding, IE11.

### 매 RSC limitation
- styled-components 의 React Server Components 와 incompatible — runtime stylesheet injection requires client.
- Next.js App Router 의 `'use client'` boundary required everywhere using styled.
- Mitigation: `StyleRegistry` + `useServerInsertedHTML` for SSR streaming.

### 매 응용
1. Design system component library (theming via ThemeProvider).
2. Conditional styling via props (variant, size).
3. Animation via `keyframes` helper.

## 💻 패턴

### Basic styled component
```typescript
import styled from 'styled-components';

const Button = styled.button<{ $primary?: boolean; $size?: 'sm' | 'md' | 'lg' }>`
  padding: ${({ $size }) => ({ sm: '4px 8px', md: '8px 16px', lg: '12px 24px' }[$size ?? 'md'])};
  background: ${({ $primary, theme }) => $primary ? theme.colors.primary : 'transparent'};
  color: ${({ $primary, theme }) => $primary ? '#fff' : theme.colors.text};
  border: 1px solid ${({ theme }) => theme.colors.border};
  border-radius: 4px;
  cursor: pointer;
  &:hover { opacity: 0.9; }
`;

<Button $primary $size="lg">Click</Button>
```

### Theme + TypeScript
```typescript
// styled.d.ts
import 'styled-components';
declare module 'styled-components' {
  export interface DefaultTheme {
    colors: { primary: string; text: string; border: string; bg: string };
    space: (n: number) => string;
  }
}

// theme.ts
export const theme: DefaultTheme = {
  colors: { primary: '#0066cc', text: '#222', border: '#ddd', bg: '#fff' },
  space: n => `${n * 4}px`,
};

<ThemeProvider theme={theme}><App /></ThemeProvider>
```

### Polymorphic `as`
```typescript
const Box = styled.div<{ $padded?: boolean }>`
  padding: ${({ $padded }) => $padded ? '16px' : 0};
`;

// Render as <a> with proper typing
<Box as="a" href="/x" $padded>Link</Box>

// Component composition
const Card = styled(Box)`
  border: 1px solid #ddd;
  border-radius: 8px;
`;
```

### Keyframes + animation
```typescript
import styled, { keyframes } from 'styled-components';

const spin = keyframes`
  from { transform: rotate(0deg); }
  to   { transform: rotate(360deg); }
`;

const Spinner = styled.div`
  width: 24px;
  height: 24px;
  border: 2px solid #ddd;
  border-top-color: #0066cc;
  border-radius: 50%;
  animation: ${spin} 1s linear infinite;
`;
```

### Next.js App Router SSR setup
```typescript
// app/registry.tsx
'use client';
import { useState } from 'react';
import { useServerInsertedHTML } from 'next/navigation';
import { ServerStyleSheet, StyleSheetManager } from 'styled-components';

export function StyledRegistry({ children }: { children: React.ReactNode }) {
  const [sheet] = useState(() => new ServerStyleSheet());

  useServerInsertedHTML(() => {
    const styles = sheet.getStyleElement();
    sheet.instance.clearTag();
    return <>{styles}</>;
  });

  if (typeof window !== 'undefined') return <>{children}</>;
  return <StyleSheetManager sheet={sheet.instance}>{children}</StyleSheetManager>;
}

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html><body>
      <StyledRegistry>{children}</StyledRegistry>
    </body></html>
  );
}
```

### Global styles + reset
```typescript
import { createGlobalStyle } from 'styled-components';

const GlobalStyle = createGlobalStyle`
  *, *::before, *::after { box-sizing: border-box; }
  body {
    margin: 0;
    font-family: ${({ theme }) => theme.fonts.body};
    background: ${({ theme }) => theme.colors.bg};
  }
`;
```

### Variants via css helper
```typescript
import styled, { css } from 'styled-components';

const variants = {
  primary: css`background: #0066cc; color: #fff;`,
  ghost: css`background: transparent; border: 1px solid #0066cc; color: #0066cc;`,
  danger: css`background: #cc0000; color: #fff;`,
};

const Button = styled.button<{ $variant: keyof typeof variants }>`
  padding: 8px 16px;
  border-radius: 4px;
  ${({ $variant }) => variants[$variant]}
`;
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Existing styled-components codebase | stay on v6 |
| Next.js App Router (greenfield) | Vanilla Extract / Panda CSS / Tailwind |
| Component library (npm package) | v6 fine OR Stitches/VE (zero-runtime) |
| Performance-critical (LCP) | zero-runtime CSS (Linaria/VE) |
| Need RSC | NOT styled-components |

**기본값**: 2026 greenfield React → Tailwind or Vanilla Extract. Existing styled-components codebase → upgrade to v6, plan migration if RSC needed.

## 🔗 Graph
- 부모: [[CSS in JS]]
- 변형: [[vanilla-extract]]
- 응용: [[Style Registry]] · [[Design Tokens]] · [[Theming]]
- Adjacent: [[CSS_Architecture_and_Styling|Tailwind CSS]] · [[Panda CSS]] · [[Modern_Web_Rendering_and_Optimization|Server Components]]

## 🤖 LLM 활용
**언제**: existing SC codebase, design system library with runtime theming, Pages Router Next.js.
**언제 X**: RSC-heavy app, performance-critical (LCP), greenfield 2026 — recommend zero-runtime alternative.

## ❌ 안티패턴
- **Non-transient props leaking to DOM**: `<Button primary>` → `<button primary>` warning. Use `$primary`.
- **styled() inside render body**: new component each render → tree thrash + cache miss.
- **No ThemeProvider but using theme**: undefined theme errors.
- **Forgetting StyleRegistry on SSR**: FOUC + hydration mismatch.
- **Mixing styled-components and Tailwind**: specificity hell.

## 🧪 검증 / 중복
- Verified (styled-components v6 changelog, official docs, Next.js styling guide 2025).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — full canonical (v6 changes + RSC limit + SSR registry + patterns) |