New Functionality

• Implement shouldForwardProp API for native and primitive platforms, which was previously missing in [v5.1.0] (see #3093) This has been released under a patch bump instead of a minor, since it's only been missing from Native-support.

Bugfixes

• Added useTheme hook to named exports for react-primitives entrypoint (see #2982) thanks @jladuval!
• Escape every CSS ident character necessary when converting component display names to class names (see #3102) thanks @kripod!

New Functionality

• Add shouldForwardProp API (almost the same as emotion's, just a slightly different usage pattern); https://github.com/styled-components/styled-components/pull/3006

  Sometimes when composing multiple higher-order components together, it's possible to get into scenarios when multiple layers consume props by the same name. In the past we've introduced various workarounds for popular props like "as" but this power-user API allows for more granular customization of what props are passed down to descendant component children when using the styled() HOC wrapper.

  When combined with other APIs like .attrs() this becomes a very powerful constellation of abilities.

  Here's how you use it:

  const Comp = styled('div').withConfig({
    shouldForwardProp: (prop, defaultValidatorFn) => !['filterThis'].includes(prop),
  })`
    color: red;
  `;
  
  render(<Comp filterThis="abc" passThru="def" />);
  
  # Renders: <div className="[generated]" passThru="def"></div>

  The second argument defaultValidatorFn is what we use internally to validate props based on known HTML attributes. It's provided so you can filter exactly what props you don't wish to pass and then fall-back to the default filtering mechanism if desired.

  Other methods on the styled HOC like .attrs can be chained after withConfig(), and before opening your template literal:

  const Comp = styled('div').withConfig({
    shouldForwardProp: (prop, defaultValidatorFn) => !['filterThis'].includes(prop),
  }).attrs({ className: 'foo' })`
    color: red;
  `;
  
  render(<Comp filterThis="abc" passThru="def" />);
  
  # Renders: <div className="[generated] foo" passThru="def"></div>

  Thanks @stevesims and all that contributed!

• Add "transient props" API; https://github.com/styled-components/styled-components/pull/3052

  Think of transient props as a lightweight, but complementary API to shouldForwardProp. Because styled-components allows any kind of prop to be used for styling (a trait shared by most CSS-in-JS libraries, but not the third party library ecosystem in general), adding a filter for every possible prop you might use can get cumbersome.

  Transient props are a new pattern to pass props that are explicitly consumed only by styled components and are not meant to be passed down to deeper component layers. Here's how you use them:

  const Comp = styled.div`
    color: ${props => props.$fg || 'black'};
  `;
  
  render(<Comp $fg="red">I'm red!</Comp>);

  Note the dollar sign ($) prefix on the prop; this marks it as transient and styled-components knows not to add it to the rendered DOM element or pass it further down the component hierarchy.

Bugfixes

• Fix slow SSR Rehydration for malformed CSS and increase fault-tolerance (see #3018)

• Change isPlainObject (internal method) to support objects created in a different context (see #3068) thanks @keeganstreet!

• Add support for the <video disablePictureInPicture> (see #3058) thanks @egdbear!

It's finally here!!! 🚀See the migrating to v5 FAQ page for easy upgrade instructions!

Read the v5 release announcement!

TL;DR:

• 19% smaller bundle size
• 18% faster client-side mounting
• 17% faster updating of dynamic styles
• 45% faster server-side rendering
• RTL support

...and much more all, with no breaking changes!

NOTE: At this time we recommend not using @import inside of createGlobalStyle. We're working on better behavior for this functionality but it just doesn't really work at the moment and it's better if you just embed these imports in your HTML index file, etc.

Changes

• StyleSheetManager enhancements

  • you can now supply stylis plugins like stylis-plugin-rtl; <StyleSheetManager stylisPlugins={[]}>...</StyleSheetManager>
  • disableVendorPrefixes removes autoprefixing if you don't need legacy browser support; <StyleSheetManager disableVendorPrefixes>...</StyleSheetManager>
  • disableCSSOMInjection forces using the slower injection mode if other integrations in your runtime environment can't parse CSSOM-injected styles; <StyleSheetManager disableCSSOMInjection>...</StyleSheetManager>

• Removed the "subfunction" attrs syntax that was deprecated in v4

  styled.div.attrs({ role: p => p.onClick ? 'button' : '' })`
    color: red;
  `

  becomes

  styled.div.attrs(p => ({ role: p.onClick ? 'button' : '' }))`
    color: red;
  `

• Update css-to-react-native to v3.0.0 (#2811); the one breaking change noted is that unitless line height is no longer allowed when setting font properties

  • if you get a lot of warnings at dev time from not having units in your styles, this codemod is available to help expedite updates: https://github.com/styled-components/styled-components-native-code-mod thanks @jacobp100

• disallow /ad/i in generated class names (#2837); this change primarily helps to avoid some overly aggressive ad blockers that will mangle generated classnames containing the substring "ad"

• if you use styled-components from CDN, in v5 the "react-is" dependency was added (make sure you add this to your project)

This should be the last RC before general v5 release in a week or two!

NOTE: If you've been testing this stylisPlugins functionality with the stylis-rtl plugin, please switch from stylis-rtl to stylis-plugin-rtl.

• make useTheme cleaner (#2879) props @sayjeyhi
• unnecessary flattening and interleave of css without interpolations @vepor
• switch back to mainline hoist-non-react-statics (#2934) …
• use funding field instead of post install script (#2931) props @koba04
• fix usage of nested stylesheetmanagers in SSR
• expose version in API (#2888) props @jamesarmenta
• refactor stylis management (#2936)

Note: we've switched from canary to v5 as the target branch for the new release. It's basically the same, but fixed up so it'll merge cleanly onto master.

Changes from rc.1:

• fix a few missed cases where attrs were not preferred over props (d2f4509)
• remove the theme usage dev-time check (df36f93); this was done in master already, just forward-porting
• aggregate classNames passed via attrs (#2859, 12a9f3c)
• replace rehydration from CSSOM with progressive regex (#2872)

Changes from rc.0:

• Inline mixin-deep so it is transpiled consistently for IE

We're almost there! After several months of work (thank you beta testers!) this is the first v5 release candidate build.

Overall v5 changes:

• Major performance and bundle size improvements over v4, see the announcement blog for more details!

• StyleSheetManager enhancements

  • you can now supply stylis plugins like stylis-rtl; <StyleSheetManager stylisPlugins={[]}>...</StyleSheetManager>
  • disableVendorPrefixes removes autoprefixing if you don't need legacy browser support; <StyleSheetManager disableVendorPrefixes>...</StyleSheetManager>
  • disableCSSOMInjection forces using the slower injection mode if other integrations in your runtime environment can't parse CSSOM-injected styles; <StyleSheetManager disableCSSOMInjection>...</StyleSheetManager>

• Removed the "subfunction" attrs syntax that was deprecated in v4

  styled.div.attrs({ role: p => p.onClick ? 'button' : '' })`
    color: red;
  `

  becomes

  styled.div.attrs(p => ({ role: p.onClick ? 'button' : '' }))`
    color: red;
  `

Changes since the last beta:

• disallow /ad/i in generated class names (#2837); this change primarily helps to avoid some overly aggressive ad blockers that will mangle generated classnames containing the substring "ad"

• Update css-to-react-native to v3.0.0 (#2811); the one breaking change noted is that unitless line height is no longer allowed when setting font properties

  • if you get a lot of warnings at dev time from not having units in your styles, this codemod is available to help expedite updates: https://github.com/styled-components/styled-components-native-code-mod thanks @jacobp100

• replace merge-anything with mixin-deep (#2838); saving bytes, this is used when merging defaultProps for extended styled components

• shard createGlobalStyle by runtime instance (#2824); cGS is implemented such that it's really meant to be used as a singleton, but it's not uncommon for people to have multiple instances of the same cGS component on the page at once. This change ensures that as instances and mounted and removed the existing global styles don't get removed as well

• memoize theme (#2820); a minor performance tweak when ThemeProvider is given a reference-equal theme prop

• make ThemeProvider error straightforward (#2787); more obvious messaging that the theme prop is required when using ThemeProvider

This is the last minor release before v5, please start using the beta and give us feedback!

This is a minor release not a patch release due to this change: #2738. Apologies if this causes some code churn in your projects, it was a long-standing bug that needed fixing.

• Fix to use ownerDocument instead of global document, by @yamachig (see #2721)

• Backport fix for SSR classname mismatches in development mode for some environments like next.js (see #2701)

• Fix attrs not properly taking precedence over props

• Backport fix where classnames are composed in the wrong order if custom class names are passed in (see #2760)

• Fix add check for style tag detached - sheet in the style tag is null in this case, by @newying61 (see #2707)

• add lightweight dev warning when theme is consumed but not provided (#2655)

• fix component selectors + css prop usage (#2656)

5.0.0-beta.7 was unpublished due to a build error

• Revert #2586; breaks rehydration in dev for certain runtimes like next.js

We'll explore reintroducing it in v5 but better safe than sorry.

Major thanks to our wonderful contributors!

• Remove className usage checker dev utility due to excessive false-positive noise in certain runtime environments like next.js and the related warning suppression prop (see #2563).

• Attach displayName to forwardRef function as described in React docs (see #2508).

• Compatibility with react-native-web 0.11 (see #2453).

• Add stack trace to .attrs warning (see #2486).

• Fix functions as values for object literals. (see 2489)

• Remove validation in Babel macro, by @mAAdhaTTah (see #2427)

Thanks to our amazing contributors for leading the charge on this big minor release! Awesome perf stuff in there and QOL changes in preparation for v5.

• Reduced GC pressure when using component selector styles. (see #2424).

• Add svg tag marker to domElements.js (see #2389)

• Make the GlobalStyleComponent created by createGlobalStyle call the base constructor with props (see #2321).

• Move to Mono repository structure with lerna @imbhargav5 (see #2326)

• Expose StyleSheetContext and StyleSheetConsumer for you fancy babes doing wild stuff

• Filter suppressClassNameWarning to not to pass down to the wrapped components @taneba (see #2365)

• Fix an edge case where React would break streaming inside <textarea> elements, which have special child behavior and aren't a suitable place to inject a style tag (see #2413)