Storybook and Chromatic tutorial

This tutorial is a quick overview that walks you through installing Storybook and integrating Chromatic visual tests. It’s intended for folks who haven’t yet used Storybook.

If you’re already using Storybook, then great!—skip to the get started guide. If you’d prefer to learn Storybook in a free 10-chapter tutorial take a look at Learn Storybook.

How Chromatic works (in brief)

Chromatic takes image snapshots of various configurations of your components. These configurations, or inputs to your components, are the specification of how the test should operate. We rely on Storybook “stories” to provide these configurations.

What is Storybook?

Storybook is the leading component explorer for React, Angular, and Vue. It provides a dedicated UI that helps you visualize, interact, and develop your component states (called “stories” in Storybook) even as you create them. When embedded in your development workflow, it’s a timesaving tool for developing apps from the ground up in a component-driven fashion.


For visual testing, Storybook helps you create visual test specifications as stories. Chromatic syncs with your stories to automate visual testing. If you change a story, your Chromatic test will also change. When a change is detected in Chromatic, we notify you, and direct you to the Storybook story that needs to be reviewed.

Install Storybook

Storybook is easy to setup. First add the package using the getstorybook command from within your app:

npx -p @storybook/cli getstorybook

# Or if you do not have npx
npm install -g @storybook/cli

The getstorybook command will install some important development dependencies, add some npm scripts to start your Storybook, and create a .storybook directory inside your app.

You can start your Storybook now with:

npm run storybook

Configure Storybook

Chances are you will not need to configure Storybook further, but if your components make use of unusual webpack loaders or other tricks, you may need to configure Storybook’s webpack config.

Setup .storybook/config.js

We recommend a few changes to the default .storybook/config.js that controls the way your Storybook loads:

import { configure } from '@storybook/react';

// 2. If you have a global CSS file, import it here:
import '../src/index.css';

// 3. Load a X.story.js file for each of your components/X.js:
const req = require.context('../src/components', true, /\.story\.js$/);
configure(() => {
  req.keys().forEach(filename => req(filename));
}, module);

You can also remove the default stories created at .storybook/stories.

Write your first stories

Let’s suppose you want to test a component named Histogram, that lives at src/components/Histogram.js.

Simply create a file called src/components/Histogram.story.js and write the following:

import React from 'react';
import { storiesOf } from '@storybook/react';

import Histogram from './Histogram';

storiesOf(Histogram.displayName, module)
  .add('loading', () => <Histogram loading />)
  .add('full data', () => <Histogram series={[{ x: 1, y: 1 }, { x: 2, y: 2 }]} />);

This will create two stories for the Histogram, and you can browse to your Storybook (which you ran earlier with npm run storybook) to view the implementation (obviously adjust the component and props above to be relevant to your app).

When you are satisfied that your stories are sensible, you can start up your first Chromatic build and set the baselines for these stories with:

./node_modules/.bin/chromatic --app-code=<your-app-code>

Grab the app code from and view the resultant build there to ensure the stories are snapshotted correctly. Read more about running tests.