Emotion is a CSS-in-JS library that provides component-scoping, encapsulation and composition for your styles.
It can be used with and without React, but this guide covers our standard use, which is alongside React. In particular it sets out how to use Emotion alongside the React implementation of our design system, Source
.
$ npm add @emotion/react
You need to install
@emotion/react
to use Source components
Emotion can be configured for TypeScript or Babel, depending on your setup. If you are using both, you only need to do one (TypeScript is simplest).
If you are using TypeScript >= 4.1 and React >= 17, it's simplest to use React's automatic runtime with TypeScript's attendant jsx and jsxImportSource compiler options.
For earlier versions, use the Babel setup described below.
In your tsconfig.json
:
{
"compilerOptions": {
"jsx": "react-jsx",
"jsxImportSource": "@emotion/react"
}
}
This tells TypeScript to use React's automatic runtime and lets TypeScript know where it can find the JSX namespace.
You can use the css
prop, in conjunction with @emotion/babel-preset-css-prop
:
$ npm add @emotion/babel-preset-css-prop -D
In your .babelrc
:
{
"presets": ["@emotion/babel-preset-css-prop"]
}
Note: If you use
@babel/preset-react
or@babel/preset-typescript
ensure that@emotion/babel-preset-css-prop
is inserted after them in your babel config.
If your app is doing server-side rendering, you need to follow Emotion's Advanced Approach to SSR setup. This is because our components use sibling selectors that may be interrupted by the way Emotion embeds <style>
tags directly into your markup.
import { css } from "@emotion/react"
const color = "darkgreen"
render(
<div
css={css`
background-color: hotpink;
&:hover {
color: ${color};
}
`}
>
This has a hotpink background.
</div>
)
We recommend reading at least the following pages on the Emotion documentation site: