This recipe assumes that you have a React app using Emotion and have just set up Storybook >=7.0 using the getting started guide. Don’t have this? Follow Emotion's installation instructions then run:
How to setup Emotion and Storybook
Emotion is a popular library for building UI components with CSS-in-JS, while Storybook is a tool for creating and testing UI components in isolation. This post will show you how to integrate these two tools to create a powerful and flexible development environment for building user interfaces with Emotion.
This post will explain how to:
- 🔌 Setup
Global
styles - 🧱 Use Emotion in your components
- 💅 Use a theme in your stories
- 🎨 Switch betweens themes in a click
If you’d like to see the example code of this recipe, check out the example repository on GitHub. Let's get started!
Install @storybook/addon-styling
Add the @storybook/addon-styling
package to your DevDependencies
Then register with Storybook in .storybook/main.js
.
How to setup GlobalStyles
UIs often have a set of global styles that are applied to every component like CSS resets, font-size
, font-family
, and colors.
In Emotion, use the Global
component to scope styles globally instead of locally (which is the library's default behavior).
Open .storybook/preview.js
and create a GlobalStyles
component which includes a font-family
. Then apply it to your stories with the withThemeFromJSXProvider
decorator by adding it to the decorators
array.
If you already have Global
in your app, you can import it into .storybook/preview.js
instead of creating it anew.
Using Emotion in components
Let’s update some of our example components to use Emotion instead. Open up the Button component in ./src/stories/button.js.
and replace it with the following code:
Now the Button
component is made with Emotion. In Storybook, you won't notice a visual difference. But if you inspect the DOM, you'll see hashed CSS-in-JS classnames.
Provide a theme for Emotion in Storybook
One of the benefits of Emotion is that you can provide a theme to help you style all of your components in a consistent way. Let's create a new ./src/theme.js
and add the following light theme:
To share this theme with the components in Storybook, you'll need to provide it to the withThemeFromJSXProvider
decorator along with @emotion/styled
's ThemeProvider component.
Now, components made with Emotion will get the theme through the theme
prop along with the styles inherited from Global
. Let's update the example components to use the theme.
Add a theme switcher tool using @storybook/addon-styling
Dark mode has become an increasingly popular offering on the web. This can be achieved quickly using themes.
Let's add the following dark theme to theme.js
Now, to get the most out of your stories, there should be a way to toggle between themes in a click.
To add the switcher, add your darkTheme
object into the the withThemeFromJSXProvider
decorator themes object
Adding a second theme will create a new toolbar menu to select your desired theme for your stories.
Get involved
Now you're ready to use Emotion with Storybook. 🎉 Check out the example repo for a quick start.
If you use Emotion at work, we'd love your help making an addon that automatically applies the configuration above. Join the maintainers in Discord to get involved, or jump into addon docs.