Migration V6

What do I need to do to migrate to v6?

v6.3.0+: Native React Server Components (RSC) support was added. Styled components now work in RSC without 'use client' directives or registry setup. See the RSC section for details.

First, let's start by updating the necessary packages to their latest versions.

If you're using NPM:

npm install styled-components@^6.0.0 stylis@^4.0.0
npm uninstall @types/styled-components

If you're using Yarn:

yarn add styled-components@^6.0.0 stylis@^4.0.0
yarn remove @types/styled-components

As styled-components now provides its own types, there's no longer a need for community ones.

TypeScript

Good news for TypeScript enthusiasts – styled-components is now natively written in TypeScript! Even if you haven't used TypeScript before, it's recommended for improving the reliability of your project as it can alert you when you're using an unknown prop or if a prop has a different value than expected.

However, if you don't use TypeScript in your project, don't worry! IDEs like VS Code will still pick up the types and provide hints as you write your code.

shouldForwardProp is no longer provided by default

If you haven't migrated your styling to use transient props ($prefix), you might notice React warnings about styling props getting through to the DOM in v6. To restore the v5 behavior, use StyleSheetManager:

import isPropValid from '@emotion/is-prop-valid';
import { StyleSheetManager } from 'styled-components';

function MyApp() {
    return (
        <StyleSheetManager shouldForwardProp={shouldForwardProp}>
        </StyleSheetManager>
    )
}

// This implements the default behavior from styled-components v5
function shouldForwardProp(propName, target) {
    if (typeof target === "string") {
        // For HTML elements, forward the prop if it is a valid HTML attribute
        return isPropValid(propName);
    }
    // For other elements, forward all props
    return true;
}

Vendor prefixes are omitted by default

As the web and browsers have matured significantly by 2023, vendor prefixing is often unnecessary. Therefore, for the v6 release, we've decided to omit automatic prefixing by default to reduce the amount of CSS delivered to a page. If you prefer the v5 behavior, you can restore it via StyleSheetManager:

import { StyleSheetManager } from 'styled-components';

function MyApp() {
    return (
        <StyleSheetManager enableVendorPrefixes>
        </StyleSheetManager>
    )
}

To accommodate this change, the original disableVendorPrefixes prop was inverted to enableVendorPrefixes; if you have disableVendorPrefixes set, you can now remove it as it's the new default.

Update stylis plugins

styled-components v6 uses the newer stylis v4; if you are providing stylisPlugins to StyleSheetManager, ensure the plugins are up-to-date. For instance, stylis-plugin-rtl released a new version to support the updated stylis.

Nested syntax handling

With the stylis v4 upgrade came a change to how nested selectors are handled which now correctly mirrors browser behavior. Specifically, pseudoselectors (e.g. :before) that do not start with & will not have the ampersand implicitly added anymore.

v5 behavior

styled.div`
  :hover { color: red; }
`
// .[classname]:hover { color: red; }

styled.div`
  &:hover { color: red; }
`
// .[classname]:hover { color: red; }

v6 behavior

styled.div`
  :hover { color: red; }
`
// .[classname] :hover { color: red; } (equivalent to .[classname] *:hover)

styled.div`
  &:hover { color: red; }
`
// .[classname]:hover { color: red; }

Transient $as and $forwardedAs props have been dropped

To reduce confusion around application order, we've dropped the transient $as and $forwardedAs props. Please use the regular as and forwardedAs props instead.

Dropped legacy withComponent() API

This change has been a long time coming. The withComponent API is no longer supported, so please use the as prop instead. You can specify as at definition time via attrs or at runtime:

import styled from 'styled-components';

const Button = styled.button`
    background: blue;
    color: white;
`;

const ButtonLink = styled(Button).attrs({ as: 'a' })``;

// These are equivalent, but `ButtonLink` allows for attaching further styling if desired.
<Button as="a" href="https://styled-components.com">
<ButtonLink href="https://styled-components.com">

Minimum Node support raised to v16+

In line with the maintenance schedule for Node, we now support v16 as the oldest runtime that's still receiving security patches.