react-native-storybook

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 v10, for v9 docs see the v9.1 docs.

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

If you are migrating from 9 to 10 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
• 🏁 Feature Flags
• 🧪 Using stories in unit tests
• 🤝 Contributing
• ✨ Examples- Storybook for React Native
• 🤖 Agent skills

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

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

For React Native CLI you can use this template

npx @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:

npm create storybook@latest

Then wrap your bundler config with the withStorybook function. It auto-detects Metro vs Re.Pack and handles everything — entry-point swapping, story generation, and optional WebSocket setup.

// metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const { withStorybook } = require('@storybook/react-native/withStorybook');

const config = getDefaultConfig(__dirname);

module.exports = withStorybook(config);

No changes to App.tsx are needed. Set STORYBOOK_ENABLED=true and run:

STORYBOOK_ENABLED=true expo start

The wrapper automatically swaps your app's entry point with Storybook's entry point. When the variable is not set, your app runs normally with zero Storybook code in the bundle.

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

Reanimated setup

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

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

Re.Pack setup

For projects using Re.Pack (Rspack/Webpack) instead of Metro, see the full Re.Pack Setup guide. You can also reference the RepackStorybookStarter project.

Expo router specific setup

For Expo Router projects, you can either use entry-point swapping (recommended) or create a dedicated Storybook route.

See the full Expo Router Setup guide for details.

Writing stories

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

import type { Meta, StoryObj } from '@storybook/react-native';
import { MyButton } from './Button';

const meta = {
  component: MyButton,
} satisfies Meta<typeof MyButton>;

export default meta;

type Story = StoryObj<typeof meta>;

export const Basic: Story = {
  args: {
    text: 'Hello World',
    color: 'purple',
  },
};

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

// .rnstorybook/main.ts
import type { StorybookConfig } from '@storybook/react-native';

const main: StorybookConfig = {
  stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
  deviceAddons: ['@storybook/addon-ondevice-controls', '@storybook/addon-ondevice-actions'],
};

export default main;

Decorators and Parameters

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

import type { Meta } from '@storybook/react';
import { Button } from './Button';