Emotion 10 has been in the works for a long time, and we’re excited that it’s finally ready. It’s a significant change that we’re very excited about with improvements to the css prop, a Global component for dynamic global styles, zero config SSR and more with an incremental adoption strategy.

The CSS Prop

Emotion has had the css prop since version 1 but it has some issues that prevent it from being widely used.

It required a babel plugin

It was not compatible with spreading an object as props

Style composition order was confusing, undocumented and could break

Emotion 10 fixes all of these issues and adds the ability to access the theme from the css prop! We’re very excited about this because we believe it’s one of the most straightforward and powerful css-in-js APIs.

Read more about the new css prop at https://emotion.sh/docs/css-prop.

Global Component

Along with the css prop, We’re adding the Global component which supports making global styles based on state and removing global styles.

Zero-Config Server-Side Rendering

Because of these new APIs, we can now support zero-config server-side rendering. If you’re using the new css prop or styled, you don’t need to do anything other than calling React’s renderToString (or renderToNodeStream). This is especially exciting for component libraries because consumers don’t need to do anything special to use a component.

You can now publish a React component to NPM with styles, and it will just work with server-side rendering without requiring consumers to do anything.

New Package Names

Because Emotion 10 has more React-specific APIs and they shouldn’t all be bundled together, it doesn’t make sense to have a package called react-emotion , so we’re changing some package names. The new APIs for React are in @emotion/core and styled is in @emotion/styled . The emotion package exports nearly the same API as in v9 except for some internals that have changed.

Use the native ref prop with styled

We’re now using forwardRef so you can replace your usages of innerRef with ref. innerRef is also going to be supported in Emotion 10 to make migration easy!

import styled from '@emotion/styled' let StyledComponent = styled.div`

color: hotpink;

` <StyledComponent ref={(node) => {}} />

Support styled shorthands without a babel plugin

Emotion 10 includes a tag list by default so you can call styled.div or any other html element without having to use the function call syntax. If you use the babel plugin or babel macro though, a different bundle is used, and you won’t have to ship the tag list because it’s compiled to the call syntax at build time!

import styled from '@emotion/styled' let StyledComponent = styled.div`

color: hotpink;

`

The as prop

Emotion 10 also supports the as prop for styled now so you can change the element that’s rendered with a prop. You can read more about Emotion’s as prop at https://emotion.sh/docs/styled#as-prop.

import styled from '@emotion/styled' const Button = styled.button`

color: hotpink;

` <Button as="a">something</Button>

Emotion’s as prop is heavily inspired by styled-components’ as prop. ❤️

Providing options via context

In Emotion 9, we added various packages to provide options such as a container element for things like iframes, nonces and other options but it was difficult to use. With Emotion 10, if you use the new APIs, you can provide options via context. This enables lots of powerful things like automatic RTL support.

React StrictMode Compatible

Emotion 10 doesn’t use any of the deprecated lifecycle hooks, so it’s now StrictMode compatible. Because we’re using the new Context API to do this, this means Emotion is only compatible with React 16.3 and above so you’ll need to upgrade to 16.3 or above to use Emotion 10.

Incremental Migration

While Emotion 10 has lots of changes, we don’t want people to have to rewrite their apps so you can upgrade to all the new APIs incrementally. A migration guide is available at https://emotion.sh/docs/migrating-to-emotion-10. We also have an ESLint plugin which does most of the upgrades for you!!