Styled Components

Common errors

• ReferenceError: React is not defined

  cause This typically occurs when using the CommonJS build of styled-components in a Node.js environment where React is not globally available or correctly imported within the module context.
  fix Ensure you are using an up-to-date version of styled-components (>=6.3.12). If still encountering this, verify your build system correctly handles CJS imports or consider migrating to ESM if possible.

• TypeError: Cannot read properties of undefined (reading 'document')

  cause This error surfaces in React Native or other non-browser environments where the `document` object is not present, indicating that the web-specific styled-components bundle is being used.
  fix Ensure your build system is correctly resolving the React Native specific entry point for styled-components (e.g., using `platform` specific extensions or aliases). Update to styled-components@6.3.12 or newer for better internal handling of `document` references in RN.

• Warning: Prop `className` did not match. Server: "sc-kIeHzt" Client: "sc-bczRLJ"

  cause This is a React hydration mismatch error, often caused by inconsistent CSS class generation between server and client during Server-Side Rendering (SSR) or Static Site Generation (SSG).
  fix Verify that your SSR setup is correctly rehydrating the styled-components stylesheet. This often involves using `ServerStyleSheet` on the server and `StyleSheetManager` with `enableCssr` on the client, ensuring the same `nonce` is used if applicable.

• Styled component's 'as' prop is not working as expected, component styles are not applied.

  cause The `as` prop allows dynamic tag rendering. If styles aren't applied, it might be due to incorrect usage, an incompatible component passed, or a conflict with other styling solutions.
  fix Ensure the component passed to the `as` prop is a valid React component or a string representing a DOM element. Also, verify that no conflicting styles or global resets are overriding styled-components' injected CSS specificity.

Warnings

• breaking Styled Components v6 dropped support for Internet Explorer 11. The build target is now ES2015, and internal dependencies like `@emotion/unitless` have been removed, impacting older browser compatibility.
  Fix: Ensure your target browser environment supports ES2015. If IE11 support is critical, consider using Styled Components v5 or transpiling your entire application to a lower ES target.
• breaking The `.attrs()` callback now receives an immutable snapshot of props, preventing unintended mutations that could affect subsequent `attrs` processing. Additionally, props supplied via `.attrs()` are automatically made optional on the resulting component's types.
  Fix: Review `.attrs()` implementations to ensure no mutation of the props object is occurring. Update TypeScript types if you were manually marking `attrs` supplied props as optional.
• gotcha In React Native environments, older versions might crash due to `document` references in the native build. Additionally, CSS syntax errors are now gracefully handled instead of causing crashes.
  Fix: Upgrade to `styled-components@6.3.12` or later for improved React Native compatibility and error handling. Ensure proper CSS syntax to avoid silent failures.
• gotcha Loading the CommonJS build in Node.js could result in a 'React is not defined' ReferenceError, especially around versions 6.3.10/6.3.11.
  Fix: Upgrade to `styled-components@6.3.12` or newer to resolve the CJS build 'React is not defined' issue. Prefer ESM imports where possible.
• gotcha Using `createGlobalStyle` with React StrictMode or in React Server Components (RSC) environments might lead to styles disappearing or incorrect behavior due to improper cleanup and style injection. Static global styles are now injected once.
  Fix: Update to `styled-components@6.3.9` or later, which includes fixes for `createGlobalStyle` compatibility with StrictMode and RSC by managing style precedence and lifecycle more effectively.
• gotcha CSS block comments containing `//` (e.g., in URLs) or `url()` CSS function values with unquoted URLs containing `//` (like `https://example.com`) could be incorrectly stripped or lead to syntax errors due to misinterpretation as JavaScript line comments.
  Fix: Upgrade to `styled-components@6.3.9` or newer, which addresses parsing issues with specific CSS comment and URL patterns.

Install

• npm install styled-components npm
• yarn add styled-components yarn
• pnpm add styled-components pnpm

Imports

• styled
  wrong:

  import { styled } from 'styled-components'

  correct:

  import styled from 'styled-components'

  The default export `styled` is a function used to create styled components, not a named export. ESM-only since v3.
• css
  wrong:

  import css from 'styled-components/macro'

  correct:

  import { css } from 'styled-components'

  `css` is a named export primarily used for defining reusable CSS snippets or for combining styles. The `/macro` import is largely deprecated or unnecessary with modern bundlers and v6.
• createGlobalStyle
  wrong:

  import { GlobalStyle } from 'styled-components'

  correct:

  import { createGlobalStyle } from 'styled-components'

  `createGlobalStyle` is a named export function that returns a component for injecting global styles. Renamed from `injectGlobal` in v4.
• ThemeProvider
  wrong:

  const ThemeProvider = require('styled-components').ThemeProvider

  correct:

  import { ThemeProvider } from 'styled-components'

  `ThemeProvider` is a named export component used for providing a theme object to all styled components in its subtree. Styled Components v6 is primarily ESM-first.

Quickstart

This quickstart demonstrates creating a global style, defining a basic styled button with props, applying conditional CSS using the `css` helper, and utilizing a `ThemeProvider` to manage design tokens across components.

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

const GlobalStyle = createGlobalStyle`
  body {
    margin: 0;
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
      'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
      sans-serif;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
  }
`;

const Button = styled.button`
  background: ${props => props.primary ? props.theme.colors.primary : 'white'};
  color: ${props => props.primary ? 'white' : props.theme.colors.primary};
  font-size: 1em;
  margin: 1em;
  padding: 0.25em 1em;
  border: 2px solid ${props => props.theme.colors.primary};
  border-radius: 3px;

  ${props => props.size === 'large' && css`
    font-size: 1.2em;
    padding: 0.5em 1.5em;
  `}
`;

const theme = {
  colors: {
    primary: '#007bff',
    secondary: '#6c757d'
  }
};

function App() {
  return (
    <ThemeProvider theme={theme}>
      <GlobalStyle />
      <div>
        <Button>Normal Button</Button>
        <Button primary>Primary Button</Button>
        <Button primary size="large">Large Primary Button</Button>
      </div>
    </ThemeProvider>
  );
}

export default App;