Updating styled components is usually as simple as npm install. Only major versions have the potential to introduce breaking changes (noted in the following release notes).

v3.4.2 07/08/2018

  • Fix a regression from #1843 that breaks deferred injection and duplicates rules, by @kitten (see #1892)

  • [TS] Fix missing generic type arguments in .d.ts, by @PzYon (see #1886)

v3.4.1 05/08/2018

  • Fixed a bug in typings where isStyledComponent was defined using an undefined variable, by @MayhemYDG (see #1876)

  • Add error system, by @probablyup (see #1881)

  • Fix "stream" module not being properly eliminated by rollup, by @probablyup

v3.4.0 02/08/2018

  • Add first-class support for functions that return objects, by @acjay (see #1820)

    const Comp = styled.div((({ color }) => ({
  • Add support for the prop variants used by Preact (autofocus, class, for), by @probablyup (see #1823)

  • Various performance improvements, by @probablyup (see #1843)

  • [TS] Revert #1798, by @Igorbek (see #1840)

  • [Internal] Add benchmarking suite, by @mxstbr (see #1833)

v3.3.3 20/06/2018

  • Fixed a regression when extending a styled(StyledComponent) introduced in 3.3.0, by @probablyup (see #1819)

  • Adjust how displayName is generated when not using Babel to properly preserve a displayName passed via withConfig, by @probablyup (see #1755)

  • [TS] Fix props being removed when indexed types are passed to WithOptionalTheme, by @devrelm (see #1806)

  • [TS] Allow TypeScript 2.9.1 to accept tagged template type argument, by @Igorbek (see #1798)

  • Add ref documentation for React.createRef(), by @julmot (see #1792)

v3.3.2 04/06/2018

Lots of 🔥fixes in this release! As always, thank you contributors for your hard work 🙇

  • Allow non-plain objects as ThemeProvider themes, by @phyllisstein (see #1780)

  • [internal] Upgrade flow-bin to latest, by @halvves (see #1748)

  • [internal] Update various CI bits, by @probablyup (see #1769)

  • Reimplement SSR stream handling as a transform stream rather than a second-order readable stream, by @probablyup (see #1768)

  • Allow React Component as attr, by @valerybugakov (see #1751)

  • Added pointer events to valid attributes check, by @plankguy (see #1790)

Note: v3.3.1 was skipped due to a bad deploy.

v2.4.1 02/06/2018

db30d2c [v2] Make TypeScript definition compatible with TS 2.9.1 - ported from #1773

v3.3.0 25/05/2018

The team is very excited to release v3.3.0, containing a number of important bugfixes and quality of life improvements to the library! This will probably be the last feature release before v4.0 (roadmap) this summer.

Thank you so much to all the people who contributed. styled-components is nothing without its community ❤️

  • Fix off-by-one error in insertRuleHelpers.js, by @migueloller (see #1749)

  • Add first-class support for objects, by @mxstbr (see #1732)

    const Component = styled.div({
      color: 'blue'
  • Fix typo in console warning about multiple instances, by @lucianbuzzo (see #1730)

  • Make the multiple instance warning criteria a little more strict to avoid badgering people running unit tests, by @probablyup (see #1693)

  • Fix React.createRef() values for innerRef being ignored in React Native, by @simonbuchan (see #1718)

  • Hoist non-react static properties on wrapped classes, by @probablyup (see #1750)

  • Support attributes prefixed by x-, by @mlecoq (see #1753)

v3.2.6 12/04/2018

The primary fix in this patch release was related to a misconfiguration in the stylis rule splitter which could cause some rules to be discarded when there was no whitespace around selector operands.

  • Fix cascade: false being erroneously set on the Stylis rule splitter (see #1677)
  • Fix typo in ComponentStyle.js comments (see #1678)
  • Accept ref forwarding components in styled constructor (see #1658)
  • Fix onInvalid check in validAttrs, by @slootsantos (see #1668)
  • Fix makeSpeedyTag's css method (see #1663)
  • Fix ComponentStyle caching strategy to take StyleSheet cache into account, by @darthtrevino (see #1634)
  • Add new test-utils to simplify finding styled-components in the DOM in unit testing scenarios, by @jamiebuilds (see #1652)
  • Add minified commonjs and esm builds for bundle size tracking (see #1681)

v3.2.4 / v3.2.5 30/03/2018

Make sure that you're installing v3.2.5 as v3.2.4 was missing some postinstall scripts for our OpenCollective message 😅


Preprocessing option in our babel plugin

The preprocess option was never here to stay and its experiment has essentially proven to be insufficient for our future goals. Check out Sweetsour/ISTF for our current effort of making styled-components more performant and adding a CSS pipeline to it:

Thanks to @Samatar26 for his PR!


Add process.env.SC_ATTR to override our style tag's marker attribute

While we're figuring out how to improve our context-drive StyleSheetManager in a stable way that works with SSR and sharded stylesheets, we would still like to provide a way for you to use styled-components that enables widgets and other use-cases where it might be necessary to prevent us from destroying your stylesheet on pages.

Specifically this affects people who are building non-SSR code that runs on pages where styled-components is already in place. In these cases our SSR rehydration would go along and happily remove another module's style tags. We haven't considered this closely as it is not a good practice in our eyes to run duplicated styled-components modules in a single app. But when you're not dealing with a single app only it might make sense.

You can now change the the style tag's styled-components attribute by bundling with the SC_ATTR environment variable. Given a setup where you can set this variable, we will now inject style tags with a different attribute, so that they're not affected by the standard SSR rehydration.

Documentation will follow soon; Thanks to @Fer0x for this change!

v3.2.3 14/03/2018


SSR memory leaks? No more!

This release simply frees up some memory by removing cloned StyleSheets when they're not needed anymore.

v3.2.2 13/03/2018


SSR accumulating non-critical CSS

If you've noticed that v3.2 would cause your server-side rendered app to output all styles it knows of, you weren't alone!

The ServerTag was accidentally cloning itself incorrectly. This meant that the ServerStyleSheet would inherit the same server styles from the “master” StyleSheet.

We now clone the tag correctly and a test is in place to ensure this doesn't happen again, since this bug came up a couple of times in past v2 releases. Thanks to @DeividasK for reporting this bug!

Fix at-rules nested inside style rules

Have some styles gone missing? In the newer >=3.1 versions that introduced speedy mode (i.e. insertRule support) some rules might not have been injected properly. This came down to insertRule being more strict with what we add. In development an incorrectly formatted CSS rule might not cause much trouble, but in production insertRule complains about it.

Stylis, more specifically stylis-rule-sheet, was generating invalid CSS when at-rules were nested inside style rules. For instance the following CSS would cause trouble:

/* input */
&:hover {
  @media (min-width: 768px) { color: papayahwip; }

/* incorrect output */
@media (min-width: 768px) {
  &:hover { color: papayahwip; }
/* ^ note the extra closing curly brace */

/* v3.2.2 fixed output */
@media (min-width: 768px) {
  &:hover { color: papayahwip; }

Fix imprecise IS_BROWSER detection

Before v3.2.2 we would check whether styled-components is running inside the browser using: typeof window !== 'undefined'. This proofed insufficient in a couple of special cases for some people, so we have now added 'HTMLElement' in window to this check.

Thanks to @danieldunderfelt for contributing this fix!

v3.2.1 07/03/2018


Incorrect SSR React Element output

We accidentally removed dangerouslySetInnerHtml in our SSR output with just some children string. This would cause some characters to be encoded.

We have corrected this mistake and more unit tests are now in place to prevent this from happening again. Thanks to @misund for reporting this mistake!

Support out-of-order injection for @import at-rules

@import rules must appear at the top of style sheets (i.e tags).

In older versions we used to shard our style tags into local and global ones. Because any CSS that is being passed to us is also reordered, so that @import rules appear at the top, often this would mean that a lone injectGlobal would get away with @import rules.

This wasn't sufficient as using @import in a component (obviously unsupported and not recommended) or in another consecutive injectGlobal would cause this logic to break, since @import wouldn't appear at the top of the stylesheet anymore.

This oversight was made worse by the fact that we stopped sharding local and global style tags. This would mean that @import could now show up fairly late in a stylesheet, instead of at its top.

In this version we introduce a patch that creates an additional style tag at the top of all other ones that we create, when necessary, which is going to accept all @import rules separately. So when you use injectGlobal and pass it an @import rule, it will now be stripped out of the rest of your CSS, and put into a completely isolated style tag.

v3.2.0 05/03/2018

This is a small minor release that introduces a couple of minor changes, but also a complete rewrite of our StyleSheet implementation. Not only is it smaller, but it also lowers the barrier to entry for new contributors (like yourself, dear reader, hopefully!) to read and understand it, and eventually contribute great new features!


Stream reconciliation function consolidateStreamedStyles

If you’ve recently migrated to streamed server-side-rendered styles, then you will be familiar with our consolidateStreamedStyles function, which was an “extended rehydration” that moved all streamed styled-components style tags when called.

Due to our refactor of our StyleSheet behaviour (see below), our new rehydration implementation now takes care of this for you automatically.

This function will now output a deprecation warning when it’s being used and effectively does nothing at all. (Take a look at its source for more information)


Rewrite and refactor StyleSheet and ServerStyleSheet

We now handle the style rules around a “style tag” based approach, which also means that our BrowserStyleSheet is a thing of the past. Depending on the environment, we will now switch between server, browser, and insertRule style tags, which all abstract their internal behaviour.

The concept of “local” vs “global” styles has been removed, in anticipation of some upcoming, future APIs, and our rehydration has been rewritten as well. You will see only a single style tag after rehydration, and now splits between style tags when injecting global styles as well. This is not a breaking change, but produces the same behaviour and specificity as it did before. (Change)

You will also notice a couple of improved and more detailed error messages—if you ever run into them that is—which will help you to understand some things that might go wrong more easily. (Change)

Style tags will now also be injected consecutively in the DOM. This means that styled-components won’t append them to the target, but will append them to its last style tag, if a first one was already injected. This should help you to predict the order of injection, when dealing with external CSS. (Change)


  • Replace murmurhash implementation and avoid destructuring tag function arguments (see #1516)


StyleSheetManager target prop

You can now pass an element to a StyleSheetManager and all the components in its context below in the tree will add their styles to new tags in the specified target.

While this is not guaranteed to work with SSR yet, it can help you to easily add runtime-styles to a different part of the DOM. For example the shadow DOM.

Multiple instance of styled-components warning

Starting from this version, style-components will log a warning when multiple instances of it are being bundled and run on the same page. Due to our rehydration this can lead to errors, where one instance of styled-components will interfere with the other. This is why we have decided to add a small warning notifying you of this, since we don’t see the practice of adding multiple styled-components instances to a single page as a best practice.

Please note that this warning won’t show up, when older version of styled-components are present, as they don’t contain the code necessary to be detected.

StyleSheet.remove API (Internal)

This is an internal API that allows us to remove rules and components from our StyleSheets, which will come in handy for some new APIs for global styles quite soon.


  • Add controlsList to validAttr list (see #1537)
  • Add foreignObject svg element (see #1544)


Enable semicolon autocompletion in styles

We accidentally disabled semicolon autocompletion in stylis, which accidentally introduced an unnoticed breaking change in a past version a while back.

Semicolon autocompletion is now enabled and back again. Thanks to @Blasz for reporting this mistake!

Nested media queries in insertRule aka production mode

Our version of stylis-rule-sheet was updated which fixes nested media queries which can now be used as is expected in production. (see #1529 and #1528)


  • Remove type="text/css"-attribute from style tag to remove warnings from w3c validator (see #1551)


Thanks to the numerous contributors and maintainers who have worked towards this release. We're sorry if some names are missing, so thanks additionally goes out to everyone who’s worked hard to get v3 out!

(In no particular order)

v3.1.6 03/02/2018

  • Bugfix for the last style tag sometimes being emitted multiple times during streaming (see #1479)

  • Bugfix for speedy mode rehydration and added handling for out-of-order style injection (see #1482)

NOTE: When calling consolidateStreamedStyles() after streaming, make sure it is called as early in the bundle as possible.

styled-components injects new CSS upon construction of new components not prerender, so consolidation must happen before any new CSS is injected on the page.

v3.1.5 01/02/2018

A quick bugfix release:

  1. Apply a workaround to re-enable "speedy" mode for IE/Edge (see #1468)
  2. Fix a memory leak in the server-side streaming logic (see #1475)

v3.1.4 30/01/2018

Hotfix: disable speedy mode for microsoft browsers to mitigate an issue with our usage of the insertRule() API. We are investigating to get it enabled again in the near future.

v3.1.1 29/01/2018

Hotfix ReactNative support, which was broken in v3.1.0.

v3.1.0 29/01/2018

See the release blogpost for more details!


Streaming server-side rendering support

React 16 introduced ReactDOMServer.renderToNodeStream, thanks to @probablyup styled-components now has full streaming server-side rendering support so you can take advantage of the faster Time-To-First-Byte! :tada:

See the documentation on the website for more information.

Much faster CSS injection in production

Thanks to @schwers we now use insertRule in production, which makes for much faster CSS injection. In benchmarks this change makes styled-components mount ~10x faster and re-render ~20x faster! :tada:


Note: Your app will probably not mount 10x faster, but we've seen Time-To-First-Interactive drop by a couple hundred milliseconds in production apps with this change!

v3.0.0 / v3.0.1 22/01/2018

This major release prepares some great features that are yet to come, so be ready for some new and exciting features soon! But for now please read on for what’s in the current (majorly awesome) release. :fire:

Breaking Changes

Shipping only flat bundles

Thanks to @Andarist we're now shipping flat bundles for each of our entries only. This means that the entire lib/ folder won’t be inside our npm package. While this might break a couple of third party libraries, it stands to reason that our internals should not have been exposed in this way before.

This new way of bundling not only makes it easier for us to perform some refactors quite soon, it also makes it easier for us to optimise our releases even more. Please check your codebases and libraries for usages of our internals and make sure not to rely on them. Open an issue please if you need help to migrate to v3.

There are bundles for Web, React Native, and React Primitives. The former two come with both ES Modules and CommonJS bundles. The Web bundle also comes with a minified bundle. We’re also now shipping source maps for each of these bundles.

Added styled.SafeAreaView and removed styled.Navigator for React Native

We’ve added the missing SafeAreaView shortcut to the native bundle, and removed the deprecated Navigator. Finally! The typings for TypeScript have been updated as well to reflect this breaking change. (see #1339)


isStyledComponent utility

Because we’re now shipping flat bundles we also wanted to provide a frequently requested utility function that determines whether a given component is a StyledComponent. This utility returns a boolean telling you just that. (see #1418)

It should make it easier to determine whether to pass on innerRef or ref for instance in some cases, and should allow you to avoid accessing some of our internals or to check whether a component has styledComponentId set.

More information on this utility can be found on our website’s API reference section.

Improved React Native Importing

From time to time, it’s easy to forget to import styled-components/native instead on React Native. So now it’s possible to import just styled-components on React Native as well and Metro Bundler will automatically switch to the native bundle. This release also deprecates the old styled-components/native import, so make sure to migrate.

We also now log a warning when the web-version of styled-components is accidentally imported in React Native, so you can be sure that the right bundle is always being used. (see #1391 and #1394)


  • As stated above, importing from styled-components/native is deprecated. Please switch to just styled-components.


  • innerRef could be undefined when using withTheme, which can lead to unexpected behaviour when spreading props or passing it on. (see #1414)
  • Nested themes were not being republished correctly when the outer theme changes (see #1382)


  • Add ESLint precommit hook, thanks to @lukebelliveau (see #1393)
  • Remove trailing commas on function arguments (not compatible with ES5 JS engines)
  • Upgrade test suites to run against react v16 (see #1426)
  • Ship source maps for all bundles to make debugging easier (see #1425)


Thanks to the numerous contributors and maintainers who have worked towards this release. We're sorry if some names are missing, so thanks additionally goes out to everyone who’s worked hard to get v3 out!

(In no particular order)

v2.4.0 22/12/2017

More stable class names

These tandem releases introduce a stabler algorithm for determining the unique hash of each component, which should lead to more consistent class names across environments. (both across dev/test/prod and across client/server when using SSR)

Big thanks to @probablyup, ref styled-components/styled-components#1381 and styled-components/babel-plugin-styled-components#112

v2.3.3 20/12/2017

v2.3.2 19/12/2017

Hotfix release, fixes an issue with v2.3.1 where attributes wouldn't be filtered correctly.

v2.3.1 19/12/2017


There's now an official styled-components badge, thanks to @iRoachie (see #1363)! Throw that on all the projects you have that use styled-components:

style: styled-components

[![style: styled-components](](


Smaller bundle size

@probablyup spent some time removing our warning messages in production mode, reducing the library size by about half a kB min+gzip! (see #1365)

Fix unminified UMD bundle

It turns out our unminified UMD build contained some process.env declarations, which broke when used via a <script> tag in your HTML. This is now fixed, thanks to @maciej-ka! (see #1355)


Our entire repo is now using Prettier, making it easy to stay consistent with our code style, thanks to @existentialism! (see #593)

Update contribution and community guidelines

We spent some time updating our contribution and community guidelines to encourage shallow contributions to ensure the longevity of this project and to remove the core team as bottlenecks from development. The TL;DR is this:


If your Pull Request is merged, regardless of content, you're eligible for push access to the organization on GitHub. This is checked for on pull request merges and an invite is sent automatically.

See our for more information on Why and How we do this, and expect a blogpost about it in the near future too. Thanks to @orta, @alloy and @ashfurrow for encouraging and helping us to explore this way of managing open source.

v2.3.0 15/12/2017

Big changes

Easier contributing

Thanks to @gribnoysup we now have a sandbox for quickly testing changes in the library in a real app! (see #1257) To start contributing locally, run these commands locally and you're all set up:

# Clone the repo locally
git clone [email protected]:styled-components/styled-components.git
# Install the dependencies in the root folder
yarn install # or npm install
# Build the library
yarn run build # or npm run build
# Install the Sandbox app dependencies
cd sandbox
yarn install # or npm install
# Start the sandbox app!
yarn run start # or npm run start

Better support for innerRef when wrapping function components

Function components cannot have refs so our innerRef prop would break when used with withTheme:

Thanks to @MatthieuLemoine, rather than attaching a ref to stateless function components (which results in a warning) we now pass the innerRef prop to it directly for it to handle. (see #1205)

Smaller changes

  • Consistently escape displayNames when creating componentId, thanks to @evan-scott-zocdoc (see #1313)
  • Add basic support for style objects in the Typescript definitions, thanks to @nbostrom (see #1123)
  • Better issue template (see #1342)

v2.2.4 29/11/2017

In this release we're fixing a little problem that'd occur when using styled-components using static styling in development together with react-hot-loader.

As hot loading updates the styles, the styled components wouldn't update as they initially judged their styles as being static. This behaviour is now being disabled in development.

v2.2.3 29/10/2017

We found a significant bug in styled-components for React Native, where components wouldn't update their styles even if they are being passed new props. 😿

If you're using React Native with styled-components v2.2.2, you probably already noticed this bug. Please update to v2.2.3.

  • Fix incorrect StyledNativeComponent#componentWillReceiveProps implementation (see #1276)

v2.2.2 24/10/2017

Another quick release with lots of bug fixes! :tada:

  • Prevent withTheme HOC from breaking when passing a theme from defaultProps, thanks to @kutyel (see #1130)
  • Refactor out theme logic in StyledComponent's componentWillMount & componentWillReceiveProps (see #1130)
  • Add onReset to valid react props list, thanks to @4urbanoff (see #1234)
  • Add support for ServerStyleSheet PropType in both StyleSheetManager and StyledComponent, thanks to @digital-flowers (see #1245)
  • Prevent component styles from being static if attrs are dynamic, thanks to @schwers (see #1219)
  • Changed 'too many classes' error to recommend attrs for frequently changed styles, thanks to @lukebelliveau (see #1213)

v2.2.1 04/10/2017

A new day, a new release. Some more performance improvements for browser-usage, some bug fixes and an all-new awesome-styled-components repo with all of the ecosystem goodness!


v2.2.0 27/09/2017

Another awesome release, mainly some performance improvements! :tada:


  • Improve mount and unmount performance for real-world use cases, thanks to @schwers
  • Fixed minification issue so you should now see slightly smaller bundles, thanks to @bkazi
  • Fixed the nonce attribute on global styles, thanks to @mzmiric5
  • Add styled.marquee, thanks to @reznord

v2.1.2 04/08/2017

This is a big patch release with a bunch of fixes! We're preparing for some big performance improvements in our next minor release, and are working towards stabilising more code to be able to refactor it for v3!

All our documentation is available on our website, as always:


Added support for webpack nonces

Albeit not the final work on this, we added some initial support webpack nonces.

Added an alias for React Native's ImageBackground component

We added the missing alias for the new ImageBackground component in React Native. Go try it out!

Snapshot testing

We switched more of our tests over to snapshot testing! We hope that this will greatly improve our development speed when implementing new features that only slightly affect our CSS fixtures in our tests.

Be tuned for more!


Deterministic ID generation

We previously had no plans for fixing the deterministic ID generation for our new v2 APIs until the new v3 code changes. But since the babel-plugin and SSR have become more important for a huge amount of our users, we now have a fix ready that should support these two methods.

.extend and .withComponent now create new component IDs during the runtime, which are still deterministic. While they're not created during compile time, this is a step towards our good SSR support, which is very important to us.


  • Refactor variable in generateAlphabeticName.js
  • Fix .extend not working after chaining it repeatedly (3 or more inheritances)
  • Fix Flow type signatures for compatibility with Flow v0.47.0


Thanks to the numerous contributors and maintainers who have contributed to this release.

(In no particular order)

The deterministic ID change is arguably the biggest reason for this patch, and the issue behind it was specifically created as a "Good first task" for contributors with either or both little experience in OSS development, or the styled-components project. Watch out for this tag in the future, if you'd like to contribute to styled-components and make a difference! :tada: