Skip to main content
Storybook for React Native provides several feature flags to enable experimental functionality and customize behavior.

​
Main Configuration Features

​
On-Device Backgrounds

Enable the built-in on-device backgrounds addon panel.
.rnstorybook/main.ts
import type { StorybookConfig } from '@storybook/react-native';

const main: StorybookConfig = {
  stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
  addons: [],
  features: {
    ondeviceBackgrounds: true,
  },
};

export default main;
​
features.ondeviceBackgrounds
boolean
default:"false"
Enable the on-device backgrounds addon.When enabled, stories can configure background colors through the backgrounds parameter, and users can switch between them in the Storybook UI.
Button.stories.tsx
export default {
  title: 'Button',
  component: Button,
  parameters: {
    backgrounds: {
      default: 'dark',
      options: {
        light: { value: '#ffffff' },
        dark: { value: '#000000' },
        gray: { value: '#888888' },
      },
    },
  },
};
This feature requires no additional package installation. It’s built into the core package.

​
React Native Options

Configure React Native-specific runtime behavior.
.rnstorybook/main.ts
import type { StorybookConfig } from '@storybook/react-native';

const main: StorybookConfig = {
  stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
  addons: [],
  reactNative: {
    playFn: false,
  },
};

export default main;
​
reactNative.playFn
boolean
default:"false"
Whether to enable play functions in stories.Play functions are not yet fully supported on React Native. This is a future option for when support is added.
const main: StorybookConfig = {
  reactNative: {
    playFn: true, // Enable play functions (experimental)
  },
};
Play functions are not yet fully supported on native platforms. Enabling this may cause issues.

​
Metro Configuration Features

​
Lite Mode

Reduce bundle size by mocking out the full Storybook UI.
metro.config.js
const { withStorybook } = require('@storybook/react-native/metro/withStorybook');

module.exports = withStorybook(config, {
  liteMode: true,
});
​
liteMode
boolean
default:"false"
Mock out the default Storybook UI to avoid installing heavy dependencies like:
  • react-native-reanimated
  • react-native-gesture-handler
  • react-native-safe-area-context
  • @gorhom/bottom-sheet
When enabled, you’ll need to provide your own UI or use headless rendering.
withStorybook(config, {
  liteMode: true,
});
Lite mode significantly reduces bundle size if you don’t need the full on-device UI.

​
Experimental MCP

Enable Model Context Protocol support for AI agent integration.
metro.config.js
const { withStorybook } = require('@storybook/react-native/metro/withStorybook');

module.exports = withStorybook(config, {
  experimental_mcp: true,
});
​
experimental_mcp
boolean
default:"false"
Enable MCP (Model Context Protocol) server support.Adds an /mcp HTTP endpoint to the channel server, allowing AI agents like Claude Code or Cursor to:
  • Query component documentation
  • Browse available stories
  • Navigate to specific stories (requires WebSockets)
withStorybook(config, {
  experimental_mcp: true,
  websockets: 'auto', // Optional, enables story selection
});
The MCP server runs on the same port as the channel server (default 7007) and provides endpoints for AI tools to interact with your Storybook.
This is an experimental feature. The API may change in future releases.

​
Global Feature Flags

Storybook automatically disables certain web-only features on React Native: 
globalThis.FEATURES = {
  measure: false,
  outline: false,
  interactions: false,
  viewport: false,
  highlight: false,
  backgrounds: false,
};
These features are not yet supported (or reimplemented) in React Native. They are disabled to avoid running incompatible code.
These are internal flags and cannot be configured directly. Use the on-device equivalents like ondeviceBackgrounds instead.

​
Environment Variables

​
Disable Telemetry

Storybook collects anonymous usage data to improve the project. Disable telemetry: 
STORYBOOK_DISABLE_TELEMETRY=true
This prevents Storybook from sending usage statistics during development and builds.

​
Conditional Storybook

Use environment variables to conditionally enable/disable Storybook:
metro.config.js
module.exports = withStorybook(config, {
  enabled: process.env.EXPO_PUBLIC_STORYBOOK_ENABLED === 'true',
});

# Development
EXPO_PUBLIC_STORYBOOK_ENABLED=true expo start

# Production
EXPO_PUBLIC_STORYBOOK_ENABLED=false expo build

​
Examples

​
All Features Enabled

.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-notes',
  ],
  features: {
    ondeviceBackgrounds: true,
  },
  reactNative: {
    playFn: false,
  },
};

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

module.exports = withStorybook(config, {
  websockets: 'auto',
  experimental_mcp: true,
  docTools: true,
  liteMode: false,
});

​
Minimal Configuration

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

const main: StorybookConfig = {
  stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
  addons: [],
};

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

module.exports = withStorybook(config, {
  liteMode: true,
  docTools: false,
});

​
Feature Support Matrix

FeatureStatusPackage
On-device BackgroundsStableCore
On-device ControlsStable@storybook/addon-ondevice-controls
On-device ActionsStable@storybook/addon-ondevice-actions
On-device NotesStable@storybook/addon-ondevice-notes
WebSocketsStableCore
Lite ModeStableCore
Play FunctionsExperimentalCore
MCP ServerExperimentalCore
InteractionsNot supported-
ViewportNot supported-
MeasureNot supported-
Web addons like @storybook/addon-backgrounds are not compatible with React Native. Use the on-device equivalents instead.

Build docs developers (and LLMs) love

Get started for freeTalk to us