Chromatic for React Native (early access)

Chromatic enables you to visual test iOS and Android apps built with React Native. It’s powered by React Native for Storybook, and your stories act as test cases.

Chromatic captures snapshots in the iOS Simulator on hosted macOS and the Android Emulator on hosted Linux, so you test exactly what your users see.

Prerequisites

Before you start, make sure you have:

• A working React Native app (Expo, Expo Router, React Native CLI, and Re.Pack are all supported)
• React Native for Storybook installed and running locally, v9.0 or higher
• A Chromatic account

npm create storybook@latest

Set up Chromatic for React Native

The Chromatic CLI uploads your built React Native Storybook to the Chromatic cloud, where it runs on real iOS Simulator and Android Emulator instances and produces visual diffs against your baselines.

1. Sign up and create a new project

Generate a unique project token for your app by signing in to Chromatic and creating a project. Sign in with your GitHub, GitLab, Bitbucket, or email.

Then reach out to your point of contact at Chromatic to enable React Native support for your project.

Steps 2 and 3 are not required if you’ve set up React Native Storybook with v10.4+. It handles all the configuration for you automatically.

2. Ensure the root shows Storybook

Regardless of which router your project uses, you must return <StorybookUI /> at the app’s root when STORYBOOK_ENABLED or EXPO_PUBLIC_STORYBOOK_ENABLED is set.

For example, in app/_layout.tsx, you can conditionally render Storybook based on the environment variable:

import { Stack } from 'expo-router';
import StorybookUI from '../.rnstorybook';

export default function RootLayout() {
  if (process.env.EXPO_PUBLIC_STORYBOOK_ENABLED === 'true') {
    return (
      <ThemeProvider value={colorScheme === 'dark' ? DarkTheme : DefaultTheme}>
        <StorybookUI />
      </ThemeProvider>
    );
  }

  // else render the normal app
  return (
    <Stack screenOptions={{ headerShown: false }}>
      <Stack.Screen name="(pages)/index" />
    </Stack>
  );
}

3. Configure Storybook UI using environment variables

Chromatic drives React Native Storybook via WebSockets and requires a few additional options to be enabled. These options must be controlled by environment variables read in .rnstorybook/index.ts.

import { view } from './storybook.requires';

const StorybookUIRoot = view.getStorybookUI({
  enableWebsockets: process.env.EXPO_PUBLIC_STORYBOOK_ENABLED === 'true',
  host: process.env.EXPO_PUBLIC_STORYBOOK_WEBSOCKET_HOST || 'localhost',
  port: parseInt(process.env.EXPO_PUBLIC_STORYBOOK_WEBSOCKET_PORT || '7007', 10),
  secured: process.env.EXPO_PUBLIC_STORYBOOK_WEBSOCKET_SECURED === 'true',
  onDeviceUI: process.env.EXPO_PUBLIC_STORYBOOK_DISABLE_UI !== 'true',
});

export default StorybookUIRoot;

4. Run your first build to establish baselines

Once you have a project token, you can establish baselines by running a Chromatic build for a new project. Chromatic builds your Storybook app, uploads it, captures a snapshot of each story, and sets those snapshots as the baseline.

Subsequent builds will generate new snapshots that are compared against existing baselines to detect UI changes.

$ npx chromatic --project-token <your-project-token>

$ yarn chromatic --project-token <your-project-token>

$ pnpm chromatic --project-token <your-project-token>

The Chromatic CLI will build your Storybook .apk and/or .app for Expo based projects.

If you have a custom build process, you can also build the artifacts yourself and pass the directory to chromatic with the --storybook-build-dir flag. More on that in the advanced configuration docs.

5. Review changes

On each build, Chromatic compares new snapshots to existing baselines from previous builds. Try modifying a component a bit and running another Chromatic build.

When tests are complete, you’ll see the build status and a link to review the changes. Click on that link to open Chromatic.

Build 2 published.

View it online at https://www.chromatic.com/build?appId=...&number=2.

The build will be marked “unreviewed” and the changes will be listed in the “Tests” table. Go through each snapshot to review the diff and approve or reject the change.

✅ Accept change: This updates the story baseline, ensuring future snapshots are compared against the latest approved version. Once a snapshot is accepted, it won’t need re-acceptance until it changes, even across git branches or merges.

❌ Deny change: This marks the change as “denied”, indicating a regression and immediately failing the build. You can deny multiple changes per build. Denying a change will force a re-capture on the next build.

Advanced configuration options

Environment Variables

All build commands invoked by the Chromatic CLI set environment variables to properly configure your Storybook for visual testing. These environment variables let you control Storybook behavior without changing code, as documented here.

The Chromatic CLI sets the following environment variables. It also sets them with the EXPO_PUBLIC_ prefix for use with Expo.

Custom build commands

For non-Expo users or setups Chromatic doesn’t currently account for, two escape-hatch options are available via the config file:

• reactNative.iosBuildCommand
• reactNative.androidBuildCommand

When set, the CLI invokes these commands instead of its defaults. The commands must output artifacts named storybook.apk and/or storybook.app to the directory specified by CHROMATIC_ARTIFACT_DIRECTORY.

Reusing an existing build

Pass --storybook-build-dir to skip all build steps except manifest.json generation. This is most useful for parallelizing native builds across CI machines: one machine builds the Android artifact, another builds the iOS artifact, and a third runs Chromatic with --storybook-build-dir pointing to the directory containing both artifacts.

The react-native-build command for Expo users

The CLI includes a react-native-build sub-command for building your React Native app that use Expo. It uses the same logic as a regular Chromatic run, but lets you split your CI pipeline and parallelize Android and iOS builds.

$ npx chromatic@latest react-native-build --help

  Build React Native Storybook for Chromatic

  Usage
    $ chromatic react-native-build [options]

  Options
    --platform    Platform to build (android, ios). Can be specified multiple times. Defaults to all platforms in Expo config.
    --output-dir  Directory to write build artifacts and log file to.

Configure CI

Integrate Chromatic into your CI pipeline to get notified about any visual changes introduced by a pull request. Chromatic will run tests when you push code and report changes via the “UI Tests” badge for your pull request.

Here’s a sample GitHub Actions workflow (for Expo) that builds the Storybook app for iOS and Android in parallel, then runs Chromatic with the generated artifacts:

name: Build

on:
  pull_request:
    types: [opened, edited, synchronize]
  push:
    branches:
      - main

jobs:
  build-ios:
    runs-on: macos-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Select Xcode
        run: sudo xcode-select -s /Applications/Xcode_26.3.app

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      - name: Install dependencies
        run: npm install

      - name: Cache CocoaPods spec repo
        uses: actions/cache@v5
        with:
          path: ~/.cocoapods
          key: cocoapods-specs-${{ hashFiles('package.json', 'app.json') }}
          restore-keys: |
            cocoapods-specs-

      - name: Cache Pods directory
        uses: actions/cache@v5
        with:
          path: ios/Pods
          key: ios-pods-${{ hashFiles('package.json', 'app.json') }}
          restore-keys: |
            ios-pods-

      - name: Build iOS
        run: npx --yes chromatic react-native-build --platform=ios --output-dir=build

      - name: Upload iOS build
        uses: actions/upload-artifact@v7
        with:
          name: ios-build
          path: build/
          retention-days: 1

  build-android:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      - name: Cache Gradle wrapper
        uses: actions/cache@v5
        with:
          path: ~/.gradle/wrapper
          key: gradle-wrapper-${{ hashFiles('package.json', 'app.json') }}

      - name: Cache Gradle dependencies
        uses: actions/cache@v5
        with:
          path: ~/.gradle/caches
          key: gradle-caches-${{ hashFiles('package.json', 'app.json') }}
          restore-keys: |
            gradle-caches-

      - name: Cache Android directory
        uses: actions/cache@v5
        with:
          path: android/
          key: android-dir-${{ hashFiles('package.json', 'app.json') }}
          restore-keys: |
            android-dir-

      - name: Install dependencies
        run: npm install

      - name: Build Android
        run: npx --yes chromatic react-native-build --platform=android --output-dir=build

      - name: Upload Android build
        uses: actions/upload-artifact@v7
        with:
          name: android-build
          path: build/
          retention-days: 1

  chromatic:
    needs: [build-ios, build-android]
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      - name: Install dependencies
        run: npm install

      - name: Download iOS build
        uses: actions/download-artifact@v8
        with:
          name: ios-build
          path: build/ios

      - name: Download Android build
        uses: actions/download-artifact@v8
        with:
          name: android-build
          path: build/android

      - name: Move Storybook static files
        run: |
          mkdir -p storybook-static
          mv build/ios/storybook.app storybook-static/
          mv build/android/storybook.apk storybook-static/

      - name: Publish to Chromatic
        run: npx --yes chromatic -d storybook-static --exit-zero-on-changes --exit-zero-on-errors
        env:
          CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

Frequently asked questions