Addons

Since react native storybook has a react native UI the web based addon panels need to be reimplemented for react native. Addons that don't include a ui should also be compatible with react native, for example msw and deep controls.

The addons made available by us are the following. There are more addons available via the community and you can also write your own addons.

Addon	Package
actions	@storybook/addon-ondevice-actions
backgrounds	@storybook/addon-ondevice-backgrounds
controls	@storybook/addon-ondevice-controls
notes	@storybook/addon-ondevice-notes

Configuration

To use on-device addons, add them to the deviceAddons property in your .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-backgrounds',
    '@storybook/addon-ondevice-actions',
    '@storybook/addon-ondevice-notes',
  ],
};

export default main;

Why deviceAddons?

On-device addons contain React Native code that can only run on the device. Storybook Core evaluates every addons entry as a preset during server-side operations (like extract or build), which fails because Node.js can't load React Native modules. List these packages in deviceAddons so they are loaded only at runtime on the device. .rnstorybook generation does not read addons.

Hiding addon panels per story

On-device addon panels can be hidden for a story with the same parameters[addonKey].disable convention used by Storybook web. When every registered panel is disabled for the selected story, the addons button and panel are hidden.

export const WithoutControls = {
  parameters: {
    controls: { disable: true },
  },
};

export const WithoutAnyAddonPanels = {
  parameters: {
    actions: { disable: true },
    backgrounds: { disable: true },
    controls: { disable: true },
    notes: { disable: true },
  },
};

Actions

The Actions addon lets you log events and actions inside your stories. It's useful for verifying component interactions and event handling.

npm install --save-dev @storybook/addon-ondevice-actions

Use the action argType to log events:

export default {
  component: Button,
  argTypes: {
    onPress: { action: 'pressed' },
  },
} satisfies Meta<typeof Button>;

Backgrounds

The Backgrounds addon allows you to change background colors of your stories directly on the device. Perfect for testing components against different backgrounds.

New: A new globals-based backgrounds API is available behind a feature flag — no extra package required, full-screen support, and alignment with Storybook web. This will become the default in the next major version. See the Backgrounds guide to opt in now.

npm install --save-dev @storybook/addon-ondevice-backgrounds

First, add the required decorator in .storybook/preview.tsx:

import { withBackgrounds } from '@storybook/addon-ondevice-backgrounds';

const preview: Preview = {
  decorators: [withBackgrounds], // This decorator is required
  parameters: {
    backgrounds: {
      default: 'light',
      values: [
        { name: 'light', value: 'white' },
        { name: 'dark', value: '#333' },
      ],
    },
  },
};

export default preview;

You can then override these background options in individual stories:

export default {
  component: MyComponent,
  parameters: {
    backgrounds: {
      default: 'warm',
      values: [
        { name: 'warm', value: 'hotpink' },
        { name: 'cool', value: 'deepskyblue' },
      ],
    },
  },
} satisfies Meta<typeof MyComponent>;

Component-level background settings will override the global settings from preview.tsx, but the decorator is still required.

Controls

Controls provides a graphical UI to dynamically edit component props without code. It supports 13 different control types optimized for mobile interfaces.

npm install --save-dev @storybook/addon-ondevice-controls @react-native-community/datetimepicker @react-native-community/slider

Basic usage:

export default {
  component: MyComponent,
  argTypes: {
    text: { control: 'text' },
    enabled: { control: 'boolean' },
    color: { control: 'color' },
    size: { control: { type: 'range', min: 0, max: 100 } },
  },
} satisfies Meta<typeof MyComponent>;

For detailed information about all supported control types, configuration options, and platform-specific features, see the Controls Addon documentation.

Notes

The Notes addon enables you to write additional documentation (text or markdown) for your stories.

npm install --save-dev @storybook/addon-ondevice-notes

Optionally install react-native-enriched-markdown for native rendering with GitHub Flavored Markdown tables, task lists, highlight, superscript, subscript and syntax-highlighted code blocks. It requires the New Architecture, so rebuild your native app afterwards (npx expo prebuild for Expo, or pod install for bare React Native). The addon detects it at runtime and otherwise falls back to the built-in JavaScript renderer, for example in Expo Go or on tvOS.

npm install react-native-enriched-markdown

Code blocks are syntax highlighted when the renderer is built with highlighting enabled (its default). Highlighting and LaTeX math each add native code to your app, so if you only need plain notes you can leave them out by adding this to your app's package.json:

{
  "enriched-markdown": {
    "enableCodeHighlight": false,
    "enableMath": false
  }
}

Add notes using the parameters field:

export default {
  component: MyComponent,
  parameters: {
    notes: `
      # Component Documentation
      This is a markdown description of the component.
      
      ## Usage
      \`\`\`tsx
      <MyComponent prop="value" />
      \`\`\`
    `,
  },
} satisfies Meta<typeof MyComponent>;