Emotion – @emotion/css (original) (raw)

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

Table of Contents

• Quick Start
• API
  • Generate Class Names — css
  • Global Styles — injectGlobal
  • Animation Keyframes — keyframes
  • Composing Class Names — cx
• Custom Instances
• Server Side Rendering
• Babel Plugin

Quick Start

Get up and running with a single import.

API

css

The css function accepts styles as a template literal, object, or array of objects and returns a class name. It is the foundation of emotion.

String Styles

Object Styles

Array of Object Styles

Global Styles

injectGlobal injects styles into the global scope and is useful for applications such as css resets or font faces.

Animation Keyframes

keyframes generates a unique animation name that can be used to animate elements with CSS animations.

String Styles

Object Styles

cx

cx is emotion's version of the popular classnames library. The key advantage of cx is that it detects emotion generated class names ensuring styles are overwritten in the correct order. Emotion generated styles are applied from left to right. Subsequent styles overwrite property values of previous styles.

Combining class names

Conditional class names

Using class names from other sources

Custom Instances

With @emotion/css/create-instance, you can provide custom options to Emotion's cache.

The main @emotion/css entrypoint can be thought of as a call to @emotion/css/create-instance with sensible defaults for most applications.

Upside

• Calling it directly will allow for some low level customization.
• Create custom names for emotion APIs to help with migration from other, similar libraries.
• Could set custom key to something other than css

Downside

• Introduces some amount of complexity to your application that can vary depending on developer experience.
• Required to keep up with changes in the repo and API at a lower level than if using @emotion/css directly

Primary use cases

• Using emotion in embedded contexts such as an <iframe/>
• Setting a nonce on any <style/> tag emotion creates for security purposes
• Use emotion with a container different than document.head for style elements
• Using emotion with custom stylis plugins

Multiple instances in a single app example

Options

createEmotion accepts the same options as createCache from @emotion/cache.