Emotion 10

[emmatown]

Emotion 10 is going to introduce some new APIs for React users.

The main aim with these new APIs is to move all insertion to inside the React tree, this enables a couple of things:

• SSR just works because we can render style elements directly into the React tree.
• Setting things like nonces, container elements and stylis plugins is much easier since it only requires a Provider at the top of the tree.
• Global styles can change over time and be removed
• It forces people to think in terms of styling elements instead of creating class names
• The css prop works without the babel plugin because it's implemented as a custom createElement (this isn't necessarily a result of moving things inside the React tree but a side-effect of the new implementation)

The main new APIs are a custom createElement for the css prop and a Global component for global styles.

Example

The exact APIs are likely to change before Emotion 10 is released.

/** @jsx jsx */
import { jsx, Global } from '@emotion/core'
import css from '@emotion/css'
import { render } from 'react-dom'

render(
  <div>
    <h1
      css={css`
        font-size: 500px;
      `}
    >
      This is really big
    </h1>
    <Global
      css={{
        body: {
          backgroundColor: 'hotpink'
        }
      }}
    />
  </div>,
  document.getElementById('root')
)

If you want to try this, look at https://github.com/emotion-js/next but note that there will be breaking changes very often for now.

Another change that emotion@10 will bring is that styled.div and etc. will work without a babel plugin. The tag list will be included in @emotion/styled but if you use @emotion/styled.macro with babel-plugin-macros or the babel plugin, styled.div will be replaced with styled('div') and @emotion/styled-base will be imported instead which doesn't include the tag list.

Compatibility with Preact and non-React-like libraries

While the majority of Emotion users use React, there are some users who don't use React and we have to figure out how to cater for them.

Non-React-like libraries

Since all the packages on the @emotion scope are very modular, we can build the current emotion APIs with the packages on the @emotion scope. This should be pretty simple.

Preact

There are only a few APIs that we use that are new.

Fragment

Fragments are only used for SSR so we could have an alternative SSR API for that similar to extractCritical now.

createContext

We could tell people to use create-react-context and essentially polyfill createContext.

forwardRef

We could conditionally use forwardRef so if it's not available then we don't use it. I'm not a huge fan of this because I think it would be confusing to tell people they should use ref when using React and innerRef when using Preact but I'm not totally sure yet.

The other option to all of this is to not support the new APIs on Preact and have Preact users use the current emotion API.

Migration

This is something I'm still thinking about and I've got some ideas about but nothing concrete yet. I'm thinking of migrating emotion.sh and seeing what's difficult, how to make incremental migration easy, what can be done automatically with codemods and what warnings would be useful to provide.

Removing extractStatic

extractStatic hasn't been something that we've encouraged for a long time so @tkh44 and I think it's time to remove it. For people who like static extraction, libraries like Linaria and css-literal-loader do static extraction much better than Emotion does so those people should use those libraries.

Only do transformations when emotion is imported

babel-plugin-emotion currently transforms anything with the names of emotion's exports. While this works it transforms things for other libraries (#626 and #344) so we should only transform . I want to do this in Emotion 10 since it could be a breaking change for some people.

TODO

• [x] Support source maps in @emotion
• [x] Try to make the keyframes API more convenient
• [x] Reorganize some internals
• [x] Add a babel plugin for hoisting objects in the css prop and adding a css call around the object since we can't use a babel macro.
• [x] Add an alternative SSR API to get around the caveats with rendering style elements
• [x] Add component selectors to @emotion/styled.macro
• [x] Add a dev warning when :first-child and selectors like it are used and recommend replacements because of problems when rendering style elements in SSR and those selectors targeting the style elements.
• [x] Move https://github.com/emotion-js/next into this repo
• [x] Decide on how versioning should work since there are lots of packages that will likely have breaking changes that don't affect most end-users so should we do major versions really often(probably not) or do independent versioning for each package and if so should we start at 1.0.0 or 10.0.0?
• [x] docs. docs. docs.
• [x] Add a deprecation notice for extractStatic in babel-plugin-emotion and add a notice to the docs (if anyone wants to submit a PR for this, that would be great!!)
• [x] Remove extractStatic
• [x] probably more stuff
• [x] Make it so the new snapshot serializer doesn't mutate the object that's passed in

[Emiliano-Bucci]

That's odd but yes, it works! Thanks a lot :)

[tkh44]

@Emiliano-Bucci, have you tried setting the jsx pragma in your babel config?

[lifeiscontent]

@mitchellhamilton in emotion 10, how would you handle the case where you have a base button and a theme button? https://gist.github.com/lifeiscontent/0c025a2fcb36cc9dc0848054411649c7

I'm really unsure what the refactor would look like here for theme button.

[emmatown]

@lifeiscontent https://gist.github.com/mitchellhamilton/af7cd8e25aac4bb3ed0871c1a6003223

[lifeiscontent]

@mitchellhamilton thanks a lot. Sorry, just 1 more question in the BaseButton, there is an option to have a disabledClassName, pressedClassName prop, how would you forward that if it was created in this case?

[emmatown]

I would probably use a child selector and target [disabled] and [aria-pressed] instead of the class names.

[lifeiscontent]

hmm ok, I guess I could do that.

[lifeiscontent]

@mitchellhamilton so with this refactor it looks like I can't use the component as a selector somewhere else.

e.g. css({[Button]: {...someStyle}});

how would I do that?

[FezVrasta]

css`
  ${Button} {
    color: red;
  }
`

is how it works with template literals, I'm not sure about object notation

[lifeiscontent]

@FezVrasta it doesn't work with either in this case, probably due to something special that happens when you wrap a component using styled.div, etc.

[lifeiscontent]

@mitchellhamilton how would you use useContext with a styled(Button)?

[JesseChrestler]

@mitchellhamilton does css in Emotion 10 become the same as a styled component at render time. From what i can see in the react tab it appears to be the case, can you confirm?

[emmatown]

does css in Emotion 10 become the same as a styled component at render time. From what i can see in the react tab it appears to be the case, can you confirm?

What do you mean by become the same as a styled component at render time?. They have different implementations if that's what you're asking.

how would you use useContext with a styled(Button)?

After hooks are stable and #967 is in, you'll be able to use hooks like useContext inside of interpolations.

[JesseChrestler]

@mitchellhamilton would Example1: const MyRedBox = <div css={css({backgroundColor:'red'})}></div> be the same as Example2: const MyRedBox = styled.div({backgroundColor:'red'}) I know the styles are obviously the same. From what i could tell it seemed like Example1 was wrapping itself around the <div> tag that it was assigned to.

This must be part of the babel transforms that rewrite the output. This changes a lot of things and the expectation around the component and how they are being used. Maybe I'm wrong so i'm just trying to verify my thoughts. Thanks.

[emmatown]

It's wrapping the output but the examples are different, the first one is creating an element, the second is creating a component.

This changes a lot of things and the expectation around the component and how they are being used.

such as?

[JesseChrestler]

such as?

The css prop becomes magical higher order components that are attaching to the ref of your element to add a class name. It seems like a lot of work just to add a class name. Is this so css will work with react-native, and other devices that don't support style sheets? What are the advantages to this approach (vs v9)

[emmatown]

magical

Using magical to describe something is very unhelpful because it doesn’t really describe what’s wrong with something. Anything could be described as magical.

attaching to the ref of your element

We don’t use refs at all, refs are forwarded to the inner element.

What are the advantages to this approach (vs v9)

• The css prop is a first-class citizen, not some hacky thing that breaks easily in certain cases + it works without the Babel plugin(especially great for create react app and codesandbox)
  • While this seems like a small thing, it completely changed how i use emotion, you don't have to think about classes or components, you have the smallest primitive in react, an element, and you can apply styles to it
• Passing options like nonces, container elements, etc. via a Provider
  • this makes emotion much easier to use with iframes(while this seems like a small use, I think it could be really useful, for example, Netlify CMS shows previews in iframes) and if people want, web components
• Zero configuration SSR, you don’t have to configure SSR at all, use react’s renderToString or renderToNodeStream and nothing else
  • The streaming performance will also be much better than the old implementation, this will be especially important when suspense SSR is out since a LOT more people will be doing streaming
  • This is especially great for component libraries since consumers don’t need to know about emotion to do ssr

Also, something that’s important to note, we’re not getting of the old APIs, if you want to keep using them, you still can, you just won’t get the advantages of the new APIs.

[lifeiscontent]

@mitchellhamilton looks like there was an option to set displayName for a styled component in the babel plugin for emotion, how would you achieve the same thing in emotion@10? Is the babel plugin still required?

[emmatown]

Yes, the babel plugin is still required for labels(except with the css prop with function components). It's enabled by default in the v10 babel plugin.

[nonewcode]

Does this work with react-native and are there any performance concerns?

[slikts]

You can literally just write a random jsx; statement anywhere in the file. Linters hate it!

Is there a workaround to having to add jsx? I'm using CRA with TS and the @jsx pragma and the unused jsx statement make for a pretty ugly look. I suppose it's related to: https://github.com/babel/babel/issues/8958

[tkh44]

Unfortunately, because CRA does not allow babel configuration, you cannot update the pragma via @emotion/babel-preset-css-prop.

[jgoux]

@slikts For CRA v1 you can use https://github.com/timarney/react-app-rewired to extend the config without ejecting. For the v2 there is https://github.com/sharegate/craco which I use and it works great! 👍 I'm not using TS so I'm not sure about the compatibility.

[slikts]

I added craco and babel-plugin-emotion and put this in craco.config.js:

module.exports = function({ env, paths }) {
  return {
    babel: {
      plugins: ["babel-plugin-emotion"],
    },
  };
};

Also: plugins: ["emotion"],

Then ran craco start, with no effect, --verbose just says craco: Added Babel plugins., and removing the jsx statement still causes ReferenceError: jsx is not defined.

I suppose there were reasons for these changes, but from my perspective emotion has taken a big step backward; it used to take just importing the template tag, but now I need to add 3 additional lines of noise: the babel pragma, the unused jsx import, and also an unused jsx statement.

[jgoux]

@slikts I don't think the @emotion/babel-preset-css-prop preset is included in babel-plugin-emotion. See here : https://emotion.sh/docs/css-prop#babel-preset

[slikts]

I installed @emotion/babel-preset-css-prop and added presets: ["@emotion/babel-preset-css-prop"], to craco.config.js, and now it claims to have applied the presets, but the only configuration that works is still with the 4 lines.

I liked emotion because it was minimal and elegant and allowed me to write CSS instead of object literals. Now it's Babel pragmas, unused imports, incompatibility with CRA/TS, and object literals in the main examples. It should have at least been released as -beta or -rc in the current state.

[tkh44]

@slikts while I agree this takes more work, you can still use import { css } from 'emotion' or import styled from '@emotion/styled' just like you have been before. You do not have to use the css prop.

import styled from '@emotion/styled'

const Button = styled.button`
  color: turquoise;
`

Now it's Babel pragmas, unused imports, incompatibility with CRA/TS, and object literals in the main examples.

We've always supported both objects and strings, still do. I don't know where you got this idea.

[slikts]

I didn't say they're unsupported, just that the examples in the readme and elsewhere used to use template literals. It would be just:

import { css } from "emotion";

render(<div className={css`
  color: red;
`} />, root);

This was what I found elegant and why I used emotion; using CSS syntax, and having a clear model that, for example, you wouldn't have to explain to a colleague if they read your code. In contrast, the changes with pragmas and seemingly unused imports are hacky and fiddly. They're using a feature of Babel that I can't even find where it's documented, and I had to piece together what it is from a random blog post. The emotion readme just drops it there as if you'd be supposed to be familiar with it. Then, to actually use CSS syntax, I have to add an another import. I basically wouldn't even try to sell the new pattern to someone else who's possibly skeptical of CSS-in-JS as such, because it doesn't look good, requires an explanation, and even with an explanation it's like magic.

[tkh44]

This was what I found elegant and why I used emotion; using CSS syntax, and having a clear model that, for example, you wouldn't have to explain to a colleague if they read your code.

Your example still works.

In contrast, the changes with pragmas and seemingly unused imports are hacky and fiddly. They're using a feature of Babel that I can't even find where it's documented, and I had to piece together what it is from a random blog post. The emotion readme just drops it there as if you'd be supposed to be familiar with it.

While it needs to be better documented, you do not have to use the css prop if you don't want it. https://emotion.sh/docs/css-prop is the only page in the documentation that shows object styles before string styles simply because that is what I prefer to use and it does not require and additional import. In order to use emotion you've always had to import the css function just as you showed in your example. Using objects with the css prop allows you to write styles without imports.

[slikts]

Your example still works.

It doesn't, the css tag function returns an object, and I'd have to know to use the vanilla package, which anyone familiarizing themselves with the library would probably miss and just see the css prop and Babel pragmas. The very first example in the readme also uses object literals.

[akullpp]

I basically wouldn't even try to sell the new pattern to someone else who's possibly skeptical of CSS-in-JS as such, because it doesn't look good, requires an explanation, and even with an explanation it's like magic.

This is a real issue, it is unacceptable to use the pragma as it seems hacky compared to styled-components. I won't introduce emotion because of this issue in a project...

[Andarist]

The good thing is that no one is forcing you to do that. You also have @emotion/styled API for grabs if you prefer using styled-components-like API.

We just don't believe that jsx pragma is a hack - you are free to feel to think differently.