React Theming: Context API and CSS-in-JS

WHY IT EXISTS: Theming exists to avoid manually passing style props like color or fontSize down through many layers of components, a practice known as prop-drilling. By centralizing design tokens (colors, spacing, fonts) in a single theme object, you ensure UI consistency and make global style changes trivial.

THE MENTAL MODEL: Imagine a global configuration file for your app's appearance. A component like <ThemeProvider> acts as a broadcast tower, sending this configuration—the theme object—to every component within its range. Any styled component can then "tune in" to this broadcast and use the shared values, ensuring a consistent look and feel.

HOW IT WORKS: You wrap a section of your React tree, or the entire app, with a <ThemeProvider> component from a CSS-in-JS library like styled-components. You pass your theme object as a prop: <ThemeProvider theme={myTheme}>. This provider uses React's Context API to make the theme object available to all descendant components. Inside a styled component, you can access theme values via props, like color: ${props => props.theme.primaryColor};. For regular function components, you can use a hook like useTheme() to access the same theme object.

WHEN TO USE IT: Use this pattern for application-wide design systems. It is the standard for implementing features like light/dark mode, user-selectable visual themes, or white-labeling a product for different clients. It's also ideal for enforcing consistent use of spacing units, font sizes, and color palettes across a large application.

WHEN NOT TO USE IT: The primary limitation is its reliance on client-side React Context. This pattern fails in environments that don't support it, most notably React Server Components (RSC). Since <ThemeProvider> is a no-op in RSC, you must use CSS custom properties (variables) for theming in modern Next.js apps that use the App Router. For simple, one-off style overrides, passing a direct prop is often simpler than creating a new theme.

ONE CANONICAL EXAMPLE: To implement a light/dark mode toggle, you define two theme objects. One for light mode: { background: '#FFF', text: '#000' } and one for dark: { background: '#000', text: '#FFF' }. Based on application state, you pass either the light or dark theme object to the main ThemeProvider. All styled components below that reference props.theme.background or props.theme.text will automatically update when the theme changes.