Storybook for React Native

A new docs site is being built for Storybook for React Native, you can find it at https://storybookjs.github.io/react-native/docs/intro/.

[!IMPORTANT]
This readme is for v9, for v8 docs see the v8.6 docs.

With Storybook for React Native you can design and develop individual React Native components without running your app.

If you are migrating from 8 to 9 you can find the migration guide here

For more information about storybook visit: storybook.js.org

[!NOTE]
Make sure you align your storybook dependencies to the same major version or you will see broken behaviour.

Table of contents

• 🚀 Getting Started
• 📒 Writing stories
• 🔌 Addons
• 📱 Hide/Show Storybook
• ⚙️ withStorybook wrapper
• 🔧 getStorybookUI
• 🧪 Using stories in unit tests
• 🤝 Contributing
• ✨ Examples

Getting Started

New project

There is some project boilerplate with @storybook/react-native and @storybook/addon-react-native-web both already configured with a simple example.

For expo you can use this template with the following command

1# With NPM
2npx create-expo-app --template expo-template-storybook AwesomeStorybook

For react native cli you can use this template

1npx @react-native-community/cli init MyApp --template react-native-template-storybook

Existing project

Run init to setup your project with all the dependencies and configuration files:

1npm create storybook@latest

The only thing left to do is return Storybook's UI in your app entry point (such as App.tsx) like this:

1export { default } from './.rnstorybook';

Then wrap your metro config with the withStorybook function as seen below

If you want to be able to swap easily between storybook and your app, have a look at this blog post

If you want to add everything yourself check out the the manual guide here.

Additional steps: Update your metro config

We require the unstable_allowRequireContext transformer option to enable dynamic story imports based on the stories glob in main.ts. We can also call the storybook generate function from the metro config to automatically generate the storybook.requires.ts file when metro runs.

Expo

First create metro config file if you don't have it yet.

1npx expo customize metro.config.js

Then wrap your config in the withStorybook function as seen below.

1// metro.config.js
2const path = require('path');
3const { getDefaultConfig } = require('expo/metro-config');
4const withStorybook = require('@storybook/react-native/metro/withStorybook');
5
6/** @type {import('expo/metro-config').MetroConfig} */
7const config = getDefaultConfig(__dirname);
8
9module.exports = withStorybook(config, {
10  // Set to false to remove storybook specific options
11  // you can also use a env variable to set this
12  enabled: true,
13  // Path to your storybook config
14  configPath: path.resolve(__dirname, './.rnstorybook'),
15  // note that this is the default so you can the config path blank if you use .rnstorybook
16
17  // Optional websockets configuration
18  // Starts a websocket server on the specified port and host on metro start
19  // websockets: {
20  //   port: 7007,
21  //   host: 'localhost',
22  // },
23});

React native

1const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
2const path = require('path');
3const withStorybook = require('@storybook/react-native/metro/withStorybook');
4const defaultConfig = getDefaultConfig(__dirname);
5
6/**
7 * Metro configuration
8 * https://reactnative.dev/docs/metro
9 *
10 * @type {import('metro-config').MetroConfig}
11 */
12const config = {};
13// set your own config here 👆
14
15const finalConfig = mergeConfig(defaultConfig, config);
16
17module.exports = withStorybook(finalConfig, {
18  // Set to false to remove storybook specific options
19  // you can also use a env variable to set this
20  enabled: true,
21  // Path to your storybook config
22  configPath: path.resolve(__dirname, './.rnstorybook'),
23  // note that this is the default so you can the config path blank if you use .rnstorybook
24
25  // Optional websockets configuration
26  // Starts a websocket server on the specified port and host on metro start
27  // websockets: {
28  //   port: 7007,
29  //   host: 'localhost',
30  // },
31});

Reanimated setup

Make sure you have react-native-reanimated in your project and the plugin setup in your babel config.

1// babel.config.js
2plugins: ['react-native-reanimated/plugin'],

Expo router specific setup

1npm create storybook@latest

choose recommended and then native

1npx expo@latest customize metro.config.js

copy the metro config

1const withStorybook = require('@storybook/react-native/metro/withStorybook');
2module.exports = withStorybook(config);

add storybook screen to app

create app/storybook.tsx

1export { default } from '../.rnstorybook';

Then add a way to navigate to your storybook route and I recommend disabling the header for the storybook route.

Heres a video showing the same setup:

https://www.youtube.com/watch?v=egBqrYg0AIg

Writing stories

In storybook we use a syntax called CSF that looks like this:

1import type { Meta, StoryObj } from '@storybook/react';
2import { MyButton } from './Button';
3
4const meta = {
5  component: MyButton,
6} satisfies Meta<typeof MyButton>;
7
8export default meta;
9
10type Story = StoryObj<typeof meta>;
11
12export const Basic: Story = {
13  args: {
14    text: 'Hello World',
15    color: 'purple',
16  },
17};

You should configure the path to your story files in the main.ts config file from the .rnstorybook folder.

1// .rnstorybook/main.ts
2import type { StorybookConfig } from '@storybook/react-native';
3
4const main: StorybookConfig = {
5  stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
6  addons: [],
7};
8
9export default main;

Decorators and Parameters

For stories you can add decorators and parameters on the default export or on a specifc story.

1import type { Meta } from '@storybook/react';
2import { Button } from './Button';
3
4const meta = {
5  title: 'Button',
6  component: Button,
7  decorators: [
8    (Story) => (
9      <View style={{ alignItems: 'center', justifyContent: 'center', flex: 1 }}>
10        <Story />
11      </View>
12    ),
13  ],
14  parameters: {
15    backgrounds: {
16      values: [
17        { name: 'red', value: '#f00' },
18        { name: 'green', value: '#0f0' },
19        { name: 'blue', value: '#00f' },
20      ],
21    },
22  },
23} satisfies Meta<typeof Button>;
24
25export default meta;

For global decorators and parameters, you can add them to preview.tsx inside your .rnstorybook folder.

1// .rnstorybook/preview.tsx
2import type { Preview } from '@storybook/react';
3import { withBackgrounds } from '@storybook/addon-ondevice-backgrounds';
4
5const preview: Preview = {
6  decorators: [
7    withBackgrounds,
8    (Story) => (
9      <View style={{ flex: 1, color: 'blue' }}>
10        <Story />
11      </View>
12    ),
13  ],
14  parameters: {
15    backgrounds: {
16      default: 'plain',
17      values: [
18        { name: 'plain', value: 'white' },
19        { name: 'warm', value: 'hotpink' },
20        { name: 'cool', value: 'deepskyblue' },
21      ],
22    },
23  },
24};
25
26export default preview;

Addons

The cli will install some basic addons for you such as controls and actions. Ondevice addons are addons that can render with the device ui that you see on the phone.

Currently the addons available are:

• @storybook/addon-ondevice-controls: adjust your components props in realtime
• @storybook/addon-ondevice-actions: mock onPress calls with actions that will log information in the actions tab
• @storybook/addon-ondevice-notes: Add some markdown to your stories to help document their usage
• @storybook/addon-ondevice-backgrounds: change the background of storybook to compare the look of your component against different backgrounds

Install each one you want to use and add them to the main.ts addons list as follows:

1// .rnstorybook/main.ts
2import type { StorybookConfig } from '@storybook/react-native';
3
4const main: StorybookConfig = {
5  // ... rest of config
6  addons: [
7    '@storybook/addon-ondevice-notes',
8    '@storybook/addon-ondevice-controls',
9    '@storybook/addon-ondevice-backgrounds',
10    '@storybook/addon-ondevice-actions',
11  ],
12};
13
14export default main;

Using the addons in your story

For details of each ondevice addon you can see the readme:

• actions
• backgrounds
• controls
• notes

Hide/Show storybook

Storybook on react native is a normal React Native component that can be used or hidden anywhere in your RN application based on your own logic.

You can also create a separate app just for storybook that also works as a package for your visual components. Some have opted to toggle the storybook component by using a custom option in the react native developer menu.

• Heres an approach for react native cli
• Heres an article about how you can do it in expo

withStorybook wrapper

withStorybook is a wrapper function to extend your Metro config for Storybook. It accepts your existing Metro config and an object of options for how Storybook should be started and configured.

1// metro.config.js
2const { getDefaultConfig } = require('expo/metro-config');
3const withStorybook = require('@storybook/react-native/metro/withStorybook');
4
5const defaultConfig = getDefaultConfig(__dirname);
6
7module.exports = withStorybook(defaultConfig, {
8  enabled: true,
9  // See API section below for available options
10});

Options

enabled

Type: boolean, default: true

Determines whether the options specified are applied to the Metro config. This can be useful for project setups that use Metro both with and without Storybook and need to conditionally apply the options. In this example, it is made conditional using an environment variable:

1// metro.config.js
2const { getDefaultConfig } = require('expo/metro-config');
3const withStorybook = require('@storybook/react-native/metro/withStorybook');
4
5const defaultConfig = getDefaultConfig(__dirname);
6
7module.exports = withStorybook(defaultConfig, {
8  enabled: process.env.WITH_STORYBOOK,
9  // ... other options
10});

onDisabledRemoveStorybook

Type: boolean, default: false

If onDisabledRemoveStorybook true and enabled is false, the storybook package will be removed from the build. This is useful if you want to remove storybook from your production build.

useJs

Type: boolean, default: false

Generates the .rnstorybook/storybook.requires file in JavaScript instead of TypeScript.

configPath

Type: string, default: path.resolve(process.cwd(), './.rnstorybook')

The location of your Storybook configuration directory, which includes main.ts and other project-related files.

websockets

Type: { host: string?, port: number? }, default: undefined

If specified, create a WebSocket server on startup. This allows you to sync up multiple devices to show the same story and arg values connected to the story in the UI.

websockets.host

Type: string, default: 'localhost'

The host on which to run the WebSocket, if specified.

websockets.port

Type: number, default: 7007

The port on which to run the WebSocket, if specified.

getStorybookUI options

You can pass these parameters to getStorybookUI call in your storybook entry point:

{
    initialSelection?: string | Object (undefined)
        -- initialize storybook with a specific story.  eg: `mybutton--largebutton` or `{ kind: 'MyButton', name: 'LargeButton' }`
    storage?: Object (undefined)
        -- {getItem: (key: string) => Promise<string | null>;setItem: (key: string, value: string) => Promise<void>;}
        -- Custom storage to be used instead of AsyncStorage
    onDeviceUI?: boolean;
        -- show the ondevice ui
    enableWebsockets?: boolean;
        -- enable websockets for the storybook ui
    query?: string;
        -- query params for the websocket connection
    host?: string;
        -- host for the websocket connection
    port?: number;
        -- port for the websocket connection
    secured?: boolean;
        -- use secured websockets
    shouldPersistSelection?: boolean;
        -- store the last selected story in the device's storage
    theme: Partial<Theme>;
        -- theme for the storybook ui
}

Using stories in unit tests

Storybook provides testing utilities that allow you to reuse your stories in external test environments, such as Jest. This way you can write unit tests easier and reuse the setup which is already done in Storybook, but in your unit tests. You can find more information about it in the portable stories section.

Contributing

We welcome contributions to Storybook!

• 📥 Pull requests and 🌟 Stars are always welcome.
• Read our contributing guide to get started, or find us on Discord and look for the react-native channel.

Looking for a first issue to tackle?

• We tag issues with Good First Issue when we think they are well suited for people who are new to the codebase or OSS in general.
• Talk to us, we'll find something to suits your skills and learning interest.

Examples

Here are some example projects to help you get started

• A mono repo setup by @axeldelafosse https://github.com/axeldelafosse/storybook-rnw-monorepo
• Expo setup https://github.com/dannyhw/expo-storybook-starter
• React native cli setup https://github.com/dannyhw/react-native-storybook-starter
• Adding a separate entry point and dev menu item in native files for RN CLI project: https://github.com/zubko/react-native-storybook-with-dev-menu
• Want to showcase your own project? open a PR and add it to the list!