Skip to main content
Storybook for React Native supports a variety of on-device addons that run directly on your mobile device, providing powerful tools for developing and testing components.

​
What are On-Device Addons?

Unlike web Storybook addons that run in a browser, on-device addons are specially designed for React Native and render natively on iOS and Android devices. They provide essential functionality like:
  • Dynamic prop editing without code changes
  • Event logging for component interactions
  • Background color switching
  • Documentation display within your app

​
Available Addons

Controls

Edit component props dynamically via a graphical UI

Actions

Log and monitor component events and interactions

Backgrounds

Change story background colors on the fly

Notes

Add markdown documentation to your stories

​
Installing Addons

Each addon is published as a separate npm package under the @storybook/addon-ondevice-* namespace. Install the addons you need: 
npm install -D @storybook/addon-ondevice-controls \
  @storybook/addon-ondevice-actions \
  @storybook/addon-ondevice-backgrounds \
  @storybook/addon-ondevice-notes

​
Configuration

Register addons in your .rnstorybook/main.ts configuration file:
.rnstorybook/main.ts
import type { StorybookConfig } from '@storybook/react-native';

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

export default main;
The order of addons in the array determines the order of their panels in the Storybook UI.

​
Addon Options

Some addons accept configuration options. Use object notation to provide options:
.rnstorybook/main.ts
const main: StorybookConfig = {
  addons: [
    // Simple string for default options
    '@storybook/addon-ondevice-actions',
    
    // Object notation for custom options
    { 
      name: '@storybook/addon-ondevice-controls',
      options: {
        // addon-specific options
      }
    },
  ],
};

​
Using Addons in Stories

Addons are configured through story parameters and metadata. Here’s a complete example:
Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-native';
import { fn } from 'storybook/test';
import { Button } from './Button';

const meta = {
  component: Button,
  args: {
    text: 'Press me',
    onPress: fn(),
  },
  argTypes: {
    color: {
      control: { type: 'color' },
    },
  },
  parameters: {
    backgrounds: {
      options: {
        light: { name: 'Light', value: '#ffffff' },
        dark: { name: 'Dark', value: '#000000' },
      },
    },
    notes: `
# Button Component

A reusable button component with customizable styling.
    `,
  },
} satisfies Meta<typeof Button>;

export default meta;

type Story = StoryObj<typeof meta>;

export const Primary: Story = {};

​
Compatibility with Web Addons

While on-device addons share similar APIs with their web counterparts, they are separate implementations optimized for React Native:
Web AddonReact Native Equivalent
@storybook/addon-controls@storybook/addon-ondevice-controls
@storybook/addon-actions@storybook/addon-ondevice-actions
@storybook/addon-backgrounds@storybook/addon-ondevice-backgrounds
@storybook/addon-notes@storybook/addon-ondevice-notes
Web Storybook documentation can be helpful as a reference, but always verify that features are supported in the React Native version.

​
Next Steps

Controls Addon

Learn how to dynamically edit component props

Actions Addon

Discover how to log component events

Build docs developers (and LLMs) love

Get started for freeTalk to us