{"id":12093,"library":"styled-components","title":"Styled Components","description":"Styled Components is a popular JavaScript library for styling React components using tagged template literals and CSS. It allows developers to write actual CSS code to style components, abstracting away the styling into reusable, themeable components. Currently at stable version 6.4.0, it maintains an active release cadence with frequent patch releases and minor updates addressing bugs, performance, and compatibility with new React features like Server Components (RSC) and React 19. Key differentiators include its powerful theming capabilities, robust server-side rendering support, and the ability to automatically prefix CSS, making it a powerful alternative to traditional CSS modules or utility-first CSS frameworks. It aims to provide a seamless developer experience by keeping styling close to the component logic.","status":"active","version":"6.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/styled-components/styled-components","tags":["javascript","react","css","css-in-js","styled-components","styling","typescript"],"install":[{"cmd":"npm install styled-components","lang":"bash","label":"npm"},{"cmd":"yarn add styled-components","lang":"bash","label":"yarn"},{"cmd":"pnpm add styled-components","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for building React applications.","package":"react","optional":false},{"reason":"Required for web-based React applications and server-side rendering. Made optional since 6.3.8 for environments without a DOM.","package":"react-dom","optional":true},{"reason":"Required for React Native applications. Used for its `css-to-react-native` peer dependency indirectly.","package":"react-native","optional":true},{"reason":"Used internally for converting CSS-in-JS to React Native styles.","package":"css-to-react-native","optional":true}],"imports":[{"note":"The default export `styled` is a function used to create styled components, not a named export. ESM-only since v3.","wrong":"import { styled } from 'styled-components'","symbol":"styled","correct":"import styled from 'styled-components'"},{"note":"`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.","wrong":"import css from 'styled-components/macro'","symbol":"css","correct":"import { css } from 'styled-components'"},{"note":"`createGlobalStyle` is a named export function that returns a component for injecting global styles. Renamed from `injectGlobal` in v4.","wrong":"import { GlobalStyle } from 'styled-components'","symbol":"createGlobalStyle","correct":"import { createGlobalStyle } from 'styled-components'"},{"note":"`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.","wrong":"const ThemeProvider = require('styled-components').ThemeProvider","symbol":"ThemeProvider","correct":"import { ThemeProvider } from 'styled-components'"}],"quickstart":{"code":"import styled, { ThemeProvider, createGlobalStyle, css } from 'styled-components';\n\nconst GlobalStyle = createGlobalStyle`\n  body {\n    margin: 0;\n    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',\n      'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',\n      sans-serif;\n    -webkit-font-smoothing: antialiased;\n    -moz-osx-font-smoothing: grayscale;\n  }\n`;\n\nconst Button = styled.button`\n  background: ${props => props.primary ? props.theme.colors.primary : 'white'};\n  color: ${props => props.primary ? 'white' : props.theme.colors.primary};\n  font-size: 1em;\n  margin: 1em;\n  padding: 0.25em 1em;\n  border: 2px solid ${props => props.theme.colors.primary};\n  border-radius: 3px;\n\n  ${props => props.size === 'large' && css`\n    font-size: 1.2em;\n    padding: 0.5em 1.5em;\n  `}\n`;\n\nconst theme = {\n  colors: {\n    primary: '#007bff',\n    secondary: '#6c757d'\n  }\n};\n\nfunction App() {\n  return (\n    <ThemeProvider theme={theme}>\n      <GlobalStyle />\n      <div>\n        <Button>Normal Button</Button>\n        <Button primary>Primary Button</Button>\n        <Button primary size=\"large\">Large Primary Button</Button>\n      </div>\n    </ThemeProvider>\n  );\n}\n\nexport default App;","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=6.4.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=6.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=6.3.12"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=6.3.10 <6.3.12"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=6.3.7 <6.3.9"},{"fix":"Upgrade to `styled-components@6.3.9` or newer, which addresses parsing issues with specific CSS comment and URL patterns.","message":"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.","severity":"gotcha","affected_versions":">=6.3.6 <6.3.9"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"ReferenceError: React is not defined"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'document')"},{"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.","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).","error":"Warning: Prop `className` did not match. Server: \"sc-kIeHzt\" Client: \"sc-bczRLJ\""},{"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.","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.","error":"Styled component's 'as' prop is not working as expected, component styles are not applied."}],"ecosystem":"npm"}