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

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

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

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

// 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

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

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

// 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

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

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 · React Styling
• 변형: Emotion · Stitches · Vanilla Extract · Linaria
• 응용: Style Registry · Design Tokens · Theming
• Adjacent: Tailwind CSS · Panda CSS · 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)