For a React project with Storybook, the usual way to add Chromatic visual tests is to create a Chromatic project, install the chromatic development dependency, and run the CLI with that project’s token. The first build establishes visual baselines; later builds compare new snapshots with them. If your UI states already live in Vitest, Playwright, or Cypress tests, Chromatic also documents runner-specific integrations.
Set up Chromatic with React and Storybook
Use this route when your React components are represented by Storybook stories. Chromatic’s documented Storybook quickstart requires Storybook 6.5 or later; check its current guidance for Node compatibility before you begin, since supported versions can change. Chromatic Quickstart
As an Amazon Associate I earn from qualifying purchases.
- Create a Chromatic project. Sign in or create an account, create a project for your app, and copy its project token. The token identifies the project to which the CLI publishes builds.
- Install the CLI package. From the React project directory, run:
npm install --save-dev chromaticChromatic also documents installation with Yarn and pnpm; use the command for the package manager your project already uses. Chromatic CLI documentation
- Publish the first build. Substitute your actual token for the placeholder and run:
npx chromatic --project-token <your-project-token>The CLI uses the project’s Storybook build by default, uploads it to Chromatic, and starts publishing and visual testing. That first run establishes the baseline snapshots.
- Review later builds. Subsequent builds compare their snapshots with the established baselines. Review the resulting changes in Chromatic and decide which visual changes should become the new expected state. Chromatic Quickstart
For component coverage, stories are the states Chromatic captures: its overview describes capturing a snapshot for each test using the project’s existing setup. Keep stories focused on meaningful visual states, such as loading, error, selected, or disabled states, rather than treating one default rendering as coverage of every appearance. Chromatic visual testing overview
Free tools Windows power users keep installed
One-click scans. No signup required.
Make the command consistent across local runs and CI
You can add a script to package.json so the same command is available to developers and automation:
#1 Best Overall
{
"scripts": {
"chromatic": "chromatic --exit-zero-on-changes"
}
}That flag changes exit behavior when visual changes occur. Choose deliberately: Chromatic’s CI documentation says UI Test or UI Review can return a nonzero exit code when changes are present. If your merge policy requires a human review rather than an automatic failed job, configure the command and CI checks to match that policy; do not copy the example flag without deciding what a diff should do. Chromatic CI documentation
Choose Storybook, Vitest, Playwright, or Cypress
Chromatic’s CLI uses Storybook by default and also documents Vitest, Playwright, and Cypress modes. The best starting point is generally the source of UI states your team already maintains, not a claim that one runner is universally superior. In runner modes, Chromatic captures a UI archive during test execution and uploads it for visual testing. Chromatic CLI documentation
| Existing UI setup | Chromatic route | Important setup point |
|---|---|---|
| Storybook stories | Default CLI mode | Use the project’s Storybook build; the documented quickstart requires Storybook 6.5 or later. |
| Vitest browser tests | --vitest |
Chromatic’s Vitest setup lists Vitest 4.0.0 or later and the @vitest/browser-playwright provider. Follow that integration guide for installation and test configuration. |
| Playwright tests | --playwright |
Use Chromatic’s Playwright-specific setup and the corresponding GitHub Action configuration if running in Actions. |
| Cypress tests | --cypress |
Use Chromatic’s Cypress-specific setup and the corresponding GitHub Action configuration if running in Actions. |
These flags select integrations; they are not substitutes for configuring the test runner and its browser setup. Start with the runner guide for the mode you choose, then add the matching flag to the Chromatic invocation. The GitHub Actions guide includes examples for running a test job, retaining its archive as an artifact, and invoking Chromatic with the appropriate Action option. CLI docs · Vitest setup · GitHub Actions guide
Run Chromatic in GitHub Actions
Chromatic’s documented Actions setup checks out the repository with full Git history, sets up Node, installs dependencies, and runs the Chromatic Action using a repository secret for the project token. The example below reflects the versions shown in Chromatic’s documentation accessed October 3, 2026; verify the current action and Node recommendations before adopting it.
name: "Chromatic"
on: push
jobs:
chromatic:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v7
with:
fetch-depth: 0
- uses: actions/setup-node@v7
with:
node-version: 24.20.0
- name: Install dependencies
run: npm ci
- name: Run Chromatic
uses: chromaui/action@latest
with:
projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}- In GitHub, open the repository’s Settings → Secrets and variables → Actions.
- Create a repository secret named
CHROMATIC_PROJECT_TOKENand set its value to the project token from Chromatic. - Save the workflow at
.github/workflows/chromatic.yml, then run it on a push or adapt the trigger to your team’s workflow. - Inspect the build and review results in Chromatic; if the project is linked to a Git provider, Chromatic documents pull-request status checks.
Chromatic documents three Action update choices: @latest, a major-version tag, or a full version tag. They trade convenience for predictability: @latest follows the latest release, while a pinned version gives you more control over when the workflow changes. Confirm available tags and current recommendations when you set up or update the workflow. Chromatic GitHub Actions guide
Forked pull requests and token safety
GitHub does not expose repository secrets to workflows triggered by forked repositories by default. Chromatic describes putting a token in workflow source as a possible workaround, but warns that anyone who can access that file could run builds on the project, potentially using snapshots. Do not commit a project token casually: decide whether fork contributions need Chromatic runs and whether the exposure is acceptable. Chromatic says a compromised token can be reset. Chromatic GitHub Actions guide
Monorepos and large Storybook builds
One project token per Chromatic subproject
For a monorepo with multiple Chromatic subprojects, each subproject needs its own token. Set the action’s working directory to the relevant app, and make sure it has a build-storybook script or specify the build script. If Storybook is already built elsewhere in the job, the action can instead receive its location through storybookBuildDir. Chromatic GitHub Actions guide
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Over the documented file limit
Chromatic’s GitHub Actions guide states a 5,000-file limit for stories and assets and recommends the zip option if a project exceeds it. Check the current guide for the exact option syntax and any changes to this limit before adjusting a large build. Chromatic GitHub Actions guide
Best Value
Troubleshoot common setup problems
- The CLI does not find or build Storybook: The default Chromatic route expects the project’s Storybook build. Confirm the command is running in the directory containing the correct Storybook configuration and build script; in a monorepo, set the working directory or provide the prebuilt directory.
- The project token is missing or the build targets the wrong project: Verify that the local command uses the token for the intended Chromatic project. In Actions, check the secret name and value in repository settings and the workflow’s
projectTokenreference. - A fork pull-request job cannot access the token: This is the default GitHub secret-protection behavior, not a reason to expose the token in source. Decide whether to skip Chromatic for fork workflows or adopt a security-reviewed alternative.
- Vitest setup fails before Chromatic runs: Check that the Vitest integration’s stated prerequisites are met, including Vitest 4.0.0 or later and the Playwright browser provider, then follow its runner-specific configuration.
- Visual differences make CI fail: Check whether UI Test or UI Review is configured to return a nonzero exit for changes. Choose whether the job should block or report changes for review, and set exit behavior to match your merge rules.
- A large build exceeds the upload limit: Count stories and assets against Chromatic’s documented 5,000-file limit and consult the guide’s
zipoption for larger projects.
Or skip the browser setup
If your immediate need is a screenshot of a page rather than baseline-based component visual tests, ScreenshotNeo is a website screenshot API and MCP server. A single request can return an image or PDF:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for parameters and response details. It accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses include X-Page-Verdict and X-Billed headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to AI agents using Claude, Cursor, or another MCP client. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. This is a page-capture service, not a replacement for Chromatic’s component-state baselines and review workflow.
Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.
Frequently Asked Questions
Does Chromatic automatically replace my approved visual baselines?
The setup guides describe later builds as comparisons against existing baselines, with changes reviewed in Chromatic; they do not establish an automatic approval policy.
Can I run the Storybook command for a Vitest integration?
No. The Storybook command uses the default Storybook mode; configure the Vitest integration and select it with Chromatic’s documented Vitest mode.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
