Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
styled
✓ import styled from 'styled-components'
✗ 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
✓ import { css } from 'styled-components'
✗ import css from 'styled-components/macro'
`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
✓ import { createGlobalStyle } from 'styled-components'
✗ import { GlobalStyle } from 'styled-components'
`createGlobalStyle` is a named export function that returns a component for injecting global styles. Renamed from `injectGlobal` in v4.
ThemeProvider
✓ import { ThemeProvider } from 'styled-components'
✗ const ThemeProvider = require('styled-components').ThemeProvider
`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.
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;
Debug
Known issues
breakingStyled 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.fixEnsure 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.
affects: >=6.4.0
breakingThe `.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.fixReview `.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.
affects: >=6.4.0
gotchaIn 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.fixUpgrade to `styled-components@6.3.12` or later for improved React Native compatibility and error handling. Ensure proper CSS syntax to avoid silent failures.
affects: >=6.3.12
gotchaLoading the CommonJS build in Node.js could result in a 'React is not defined' ReferenceError, especially around versions 6.3.10/6.3.11.fixUpgrade to `styled-components@6.3.12` or newer to resolve the CJS build 'React is not defined' issue. Prefer ESM imports where possible.
affects: >=6.3.10 <6.3.12
gotchaUsing `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.fixUpdate 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.
affects: >=6.3.7 <6.3.9
gotchaCSS 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.fixUpgrade to `styled-components@6.3.9` or newer, which addresses parsing issues with specific CSS comment and URL patterns.
affects: >=6.3.6 <6.3.9
Errors
Common errors & fixes
ReferenceError: React is not defined
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.
fixEnsure 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')
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.
fixEnsure 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"
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).
fixVerify 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.
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.
fixEnsure 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.
Audit
Dependencies
reactrequiredCore dependency for building React applications.
react-domoptionalRequired for web-based React applications and server-side rendering. Made optional since 6.3.8 for environments without a DOM.
react-nativeoptionalRequired for React Native applications. Used for its `css-to-react-native` peer dependency indirectly.
css-to-react-nativeoptionalUsed internally for converting CSS-in-JS to React Native styles.