introduction.mdx

title
Introduction

Emotion is a library designed for writing css styles with JavaScript. It provides powerful and predictable style composition in addition to a great developer experience with features such as source maps, labels, and testing utilities. Both string and object styles are supported.

---

There are two primary methods of using Emotion. The first is framework agnostic and the second is for use with React.

Framework Agnostic

npm i @emotion/css

@emotion/css documentation

The @emotion/css package is framework agnostic and the simplest way to use Emotion.

• Requires no additional setup, babel plugin, or other config changes.

• Has support for auto vendor-prefixing, nested selectors, and media queries.

• You simply prefer to use the css function to generate class names and cx to compose them.

• Server side rendering requires additional work to set up

// @live
import { css } from '@emotion/css'

const color = 'white'

render(
  <div
    className={css`
      padding: 32px;
      background-color: hotpink;
      font-size: 24px;
      border-radius: 4px;
      &:hover {
        color: ${color};
      }
    `}
  >
    Hover to change color.
  </div>
)

React

npm i @emotion/react

The @emotion/react package requires React and is recommended for users of that framework if possible.

• Best when using React with a build environment that can be configured.

• css prop support

  • Similar to the style prop, but also has support for auto vendor-prefixing, nested selectors, and media queries.

  • Allows developers to skip the styled API abstraction and style components and elements directly.

  • The css prop also accepts a function that is called with your theme as an argument allowing developers easy access to common and customizable values.

  • Reduces boilerplate when composing components and styled with emotion.

• Server side rendering with zero configuration.

• Theming works out of the box.

• ESLint plugins available to ensure proper patterns and configuration are set.

@emotion/react css prop documentation

// @live
import { css } from '@emotion/react'

const color = 'white'

render(
  <div
    css={css`
      padding: 32px;
      background-color: hotpink;
      font-size: 24px;
      border-radius: 4px;
      &:hover {
        color: ${color};
      }
    `}
  >
    Hover to change color.
  </div>
)

npm i @emotion/styled @emotion/react

The @emotion/styled package is for those who prefer to use the styled.div style API for creating components.

@emotion/styled documentation

// @live
import styled from '@emotion/styled'

const Button = styled.button`
  padding: 32px;
  background-color: hotpink;
  font-size: 24px;
  border-radius: 4px;
  color: black;
  font-weight: bold;
  &:hover {
    color: white;
  }
`

render(<Button>This my button component.</Button>)

Browser requirements

Emotion supports all popular browsers and Internet Explorer 11.

Libraries that Inspired Us

• "original" glam
• glam
• glamor
• styled-components
• glamorous