Guide · Open source

How to use Emotion: install @emotion/react and style React components

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Emotion is an open-source CSS-in-JS library. Instead of keeping styles in separate stylesheet files, you write them as strings or JavaScript objects inside your components. This guide shows you how to install it, apply styles with the css prop, and decide whether the optional Babel plugin is worth adding. You will need basic JavaScript and familiarity with Node.js and npm.

Emotionemotion-js/emotion · ★ 18k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm that Node.js and npm are installed on your machine.
2Install the core package. Run npm install --save @emotion/react in your project folder.
3Import jsx. Add the /** @jsx jsx */ pragma and import jsx from @emotion/react at the top of your component file.
4Add a css prop. Pass a JavaScript object of CSS properties to the css prop on an element.
5Explore composition. Read the Composition and Styled Components docs to reuse styles across components.
6Decide on the Babel plugin. Leave it out at first. Add it later if you want the optimizations described in its documentation.

What Emotion is and when it fits

Emotion lets you style an app by writing string or object styles directly alongside your components. The project describes its styling as predictable, which it says avoids CSS specificity problems, and it provides source maps and labels to make debugging easier.

The README focuses on React examples, so React developers are the clearest fit. Designers or people who do not write JavaScript will find that styling with Emotion means writing code.

Good fit: React developers who want styles colocated with components.
Good fit: teams that want to combine and reuse style objects in JavaScript.
Good fit: projects that want labelled class names and source maps while debugging.
Poor fit: projects that prefer plain CSS or CSS modules and do not want a runtime styling library.

Install Emotion with npm

You need Node.js and npm. Install the core React package from your project folder with the command below. The README's quick start uses this single package to get going.

Prerequisites: Node.js and npm.

npm install --save @emotion/react

Apply styles with the css prop

The quick start shows a component that receives a css prop. The prop takes a JavaScript object of CSS properties. In the example, the div gets a hotpink text colour. The README's example uses a JSX pragma comment at the top of the file, which imports jsx from @emotion/react.

Spread the incoming props onto the element as the example does, so callers can still pass their own props through.

Import jsx from @emotion/react when using the pragma approach shown in the README.
Pass styles as an object to the css prop, for example color set to hotpink.

/** @jsx jsx */
import { jsx } from '@emotion/react'

let SomeComponent = props => {
  return (
    <div
      css={{
        color: 'hotpink'
      }}
      {...props}
    />
  )
}

Use composition and styled components

Emotion's docs cover several patterns that the README links to: the css prop, styled components, composition, nested selectors and media queries. Composition is the key idea behind reusing style objects across components. The README also lists @emotion/styled as a package for styled components, which is a separate install you can look up in the docs.

Check the docs pages for exact syntax for nested selectors and media queries rather than guessing it from this guide.

Read the Composition page to reuse style objects.
Read the Nested Selectors page for selectors inside a style block.
Read the Media Queries page for responsive styles.
Read the Styled Components page for the styled API.

Decide whether to add the Babel plugin

The Babel plugin is not required. According to the README, it enables some optimizations and customizations that could benefit your project. The plugin's feature table and documentation are in the emotion repository under packages/babel-plugin.

Start without it if you are learning. Add it later if you want the extra optimizations the README describes.

Debug with source maps and labels

The project's description says source maps and labels give Emotion a strong developer experience. Labels make the generated class names easier to recognise when you inspect elements in browser developer tools. The README says heavy caching in production supports performance.

Check your own build setup to confirm source maps reach your browser, since the README does not describe that configuration in detail.

What people use it for

Styling React components with colour and layout defined beside the component code.
Building reusable style objects that teams combine across several components.
Debugging styles with source maps and labelled class names in development.
Adding responsive styles through the Media Queries pattern in the docs.
Using the Babel plugin for optional build-time optimizations in production projects.

Frequently asked questions

Is Emotion free to use?

Yes. The repository is licensed under MIT. Check the LICENSE file in the repository for the full terms before you ship a product.

What do I need to install Emotion?

You need Node.js and npm. Then run npm install --save @emotion/react to add the core React package.

Do I need the Babel plugin?

No. The README says the Babel plugin is not required but enables some optimizations and customizations that may help your project.

Can I use Emotion without React?

The README focuses on React examples, so it does not give a full framework-agnostic setup. Read the docs for any other framework before you commit.

What are the alternatives to Emotion?

The README lists styled-components, Emotion's own @emotion/styled, Vanilla Extract and Linaria as comparable projects. Compare them on how they handle styles at runtime and at build time.

Is Emotion good for beginners?

It suits developers who already write JavaScript and React. Designers or non-programmers will need to learn code to style pages with it.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Emotion suits React developers who want styles next to their components, reusable style objects in JavaScript, and debugging aids like source maps and labels. It is a poor choice for people who want plain CSS or CSS modules, or who do not write JavaScript. Check the docs for setups beyond React, since the README focuses on React examples.

Install options & downloads