Announcing Emotion 10!
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!!
Emotion 10 is a massive release, and we can’t cover all of the little changes, so for a more a more complete list of changes, see the changelog on GitHub.
I want to give a huge thanks to Sunil Pai for the css prop in glamor and glam. They were both huge inspirations for emotion 10’s css prop, emotion 10 wouldn’t exist(or emotion at all 😛) without Sunil’s fantastic ideas ❤️. I also want to give a big thanks to Thinkmill for giving me so much time to work on emotion!
