Skip to main content


In this guide, you will learn how to set up a site with the CSS-in-JS library Emotion.

Emotion is a performant and flexible CSS-in-JS library. Building on many other CSS-in-JS libraries, it allows you to style apps quickly with string or object styles. It has predictable composition to avoid specificity issues with CSS. With source maps and labels, Emotion has a great developer experience and great performance with heavy caching in production.

Server side rendering works out of the box in Emotion. You can use React’s renderToString or renderToNodeStream methods directly without any extra configuration. extractCritical feature removes unused rules that were created with emotion and helps loading pages faster.

First, open a new terminal window and run the following to create a new site:

npx gatsby new emotion-tutorial

Second, install the necessary dependencies for Emotion and Gatsby.

npm install --save gatsby-plugin-emotion @emotion/core @emotion/styled

And then add the plugin to your site’s gatsby-config.js:

module.exports = {
  plugins: [`gatsby-plugin-emotion`],

Then in your terminal run npm start to start the Gatsby development server.

Now let’s create a sample Emotion page at src/pages/index.js:

import React from "react"
import styled from "@emotion/styled"
import { css } from "@emotion/core"

const Container = styled.div`
  margin: 3rem auto;
  max-width: 600px;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;

const UserWrapper = styled.div`
  display: flex;
  align-items: center;
  margin-top: 0;
  margin-right: auto;
  margin-bottom: 12px;
  margin-left: auto;
  &:last-child {
    margin-bottom: 0;

const Avatar = styled.img`
  flex-grow: 0;
  flex-shrink: 0;
  flex-basis: 96px;
  width: 96px;
  height: 96px;
  margin: 0;

const Description = styled.div`
  flex: 1;
  margin-left: 18px;
  padding: 12px;

const Username = styled.h2`
  margin: 0 0 12px 0;
  padding: 0;

const Excerpt = styled.p`
  margin: 0;
// Using css prop provides a concise and flexible API to style the components. //
const underline = css`
  text-decoration: underline;

const User = props => (
    <Avatar src={props.avatar} alt="" />

export default () => (
    <h1 css={underline}>About Emotion</h1>
    <p>Emotion is uber cool</p>
      username="Jane Doe"
      excerpt="I'm Jane Doe. Lorem ipsum dolor sit amet, consectetur adipisicing elit."
      username="Bob Smith"
      excerpt="I'm Bob smith, a vertically aligned type of guy. Lorem ipsum dolor sit amet, consectetur adipisicing elit."

edit this page on GitHub