🇺🇦 STOP WAR IN UKRAINE 🇺🇦
Avatar

Emotion

Best Practices

✏️ Edit this page

Emotion is an extremely flexible library, but this can make it intimidating, especially for new users. This guide contains several recommendations for how to use Emotion in your application. Keep in mind, these are only recommendations, not requirements!

Recommendations

Use TypeScript and object styles

You don't get Intellisense or type checking when using CSS strings, e.g. css`color: blue`. You can improve the developer experience and prevent style bugs by using TypeScript and object styles, which enable Intellisense and some static type checking:

const myCss = css({
  color: 'blue',
  grid: 1 // Error: Type 'number' is not assignable to type 'Grid | Grid[] | undefined'
})

Colocate styles with components

With normal CSS, the styles for a component are defined in a separate file. This makes maintenance more difficult because it's harder to tell which components use a given piece of CSS, and you can easily forget to update the relevant CSS after modifying a component. One of the main benefits of Emotion is that you can colocate your styles with your components. All this means is that the CSS for a component should be in the same file as the component itself.

Consider how you will share styles

There are two main approaches for sharing styles across an Emotion application.

To illustrate the two methods, let's imagine we're developing an application that needs to display error messages in many different components. All of the error messages should be red and bold. Some error messages should also use a large font.

Method 1: Export CSS objects

The simplest way to share styles is to export CSS from a shared file and then import that CSS in many places:

export const errorCss = css({
  color: 'red',
  fontWeight: 'bold'
})

// Use arrays to compose styles
export const largeErrorCss = css([errorCss, { fontSize: '1.5rem' }])

Then, in one of your components:

import { errorCss } from '...'

return <p css={errorCss}>Failed to fizzle the frozzle.</p>

This method is great when you only want to share CSS between components. A potential drawback of this method is that shared styles are not colocated with the components that use them.

Method 2: Share styles via component reuse

This method is slightly more complex but arguably more powerful than the previous method.

export function ErrorMessage({ className, children }) {
  return (
    <p css={{ color: 'red', fontWeight: 'bold' }} className={className}>
      {children}
    </p>
  )
}

// `fontSize: '1.5rem'` is passed down to the ErrorMessage component via the
// className prop, so ErrorMessage must accept a className prop for this to
// work!
export function LargeErrorMessage({ className, children }) {
  return (
    <ErrorMessage css={{ fontSize: '1.5rem' }} className={className}>
      {children}
    </ErrorMessage>
  )
}

Then, in one of your components:

import { ErrorMessage } from '...'

return <ErrorMessage>Failed to fizzle the frozzle.</ErrorMessage>

Advantages of sharing styles via component reuse include:

  • Component reuse allows you to share both logic and styles. You can easily add additional props and functionality to the ErrorMessage component with limited refactoring.
  • Styles are always colocated with their components.

Use the style prop for dynamic styles

The css prop or styled should be used for static styles, while the style prop (inline styles) should be used for truly dynamic styles. By dynamic styles, we mean styles that change frequently or are unique to a single element.

Imagine you are displaying a list of user avatars in a forum application. Every avatar shares certain static CSS, like width: 40px and border-radius: 50%, but the avatar image is set via a background-image rule whose value is different for each avatar. If you pass all of this CSS through the CSS prop, you'll end up with a lot of nearly-duplicate CSS in the document. With 3 avatars, Emotion will create something like:

<style>
  .css-1udhswa {
    border-radius: 50%;
    width: 40px;
    height: 40px;
    background-image: url(https://i.pravatar.cc/150?u=0);
  }

  .css-1cpwmbr {
    border-radius: 50%;
    width: 40px;
    height: 40px;
    background-image: url(https://i.pravatar.cc/150?u=1);
  }

  .css-am987o {
    border-radius: 50%;
    width: 40px;
    height: 40px;
    background-image: url(https://i.pravatar.cc/150?u=2);
  }
</style>

Now imagine how much CSS there would be if there were 100 avatars on the page!

You should also use the style prop if the styles will be updated frequently. If your application lets a user drag and drop an element, you likely have a transform property like

{
  transform: `translate(${x}px, ${y}px)`
}

This property should go through the style prop since x and y will change rapidly as the element is dragged.

Advanced: CSS variables with style

CSS variables can be used with the style prop to keep the CSS in a single place while "deferring" the actual value of a property. Going back to the avatar example above, you could define the following static CSS using the css prop:

.avatar {
  border-radius: 50%;
  width: 40px;
  height: 40px;
  background-image: var(--background-image);
}

Then, for each avatar, you render an element which sets the value of the --background-image CSS variable:

function Avatar({ imageUrl }) {
  return <div className="avatar" style={{ '--background-image': imageUrl }} />
}

If you're using TypeScript, you'll have to use a type assertion like style={{ ['--background-image' as any]: imageUrl }} as explained here.

If using React, prefer @emotion/react or @emotion/styled over @emotion/css

@emotion/react and @emotion/styled generally offer a better developer experience over class names (@emotion/css) when using React.

Use the css prop or @emotion/styled, but not both

While the css prop and styled can peacefully coexist, it's better to pick one approach and use it consistently across your codebase. Whether you choose the css prop or styled is a matter of personal preference. (If you're curious, the css prop is more popular among the maintainers of Emotion.)

Consider defining styles outside your components

For example:

import { css } from '@emotion/react'

const cardCss = {
  self: css({
    backgroundColor: 'white',
    border: '1px solid #eee',
    borderRadius: '0.5rem',
    padding: '1rem'
  }),

  title: css({
    fontSize: '1.25rem'
  })
}

export function Card({ title, children }) {
  return (
    <div css={cardCss.self}>
      <h5 css={cardCss.title}>{title}</h5>
      {children}
    </div>
  )
}

Benefits of this approach:

  • Styles are only serialized once, instead of on every render.
  • It's no longer possible to accidentally pass dynamic styles through the css prop.
  • The JSX is arguably more readable with the CSS separated out into a different part of the file.

Define colors and other style constants as JavaScript variables

Don't repeat yourself! If you are using a color, padding, border radius, .etc throughout your application, add it to your theme or define it as a JavaScript constant, like

export const colors = {
  primary: '#0d6efd',
  success: '#198754',
  danger: '#dc3545'
}

Don't use a theme unless your app supports multiple themes (or will eventually support multiple themes)

Emotion allows you to define a theme which you can use in style rules across your application. This feature is awesome if your app has multiple themes, like light mode and dark mode.

On the other hand, if your app will only ever have a single theme, it's simpler to define colors and other style variables as JavaScript constants.

Additional Reading