@chromatic-com/storybook
@chromatic-com/storybook is Chromatic's official Visual Tests addon for Storybook. It adds a panel that sends stories to the hosted Chromatic service, compares new browser snapshots with accepted baselines, reports visual changes beside the story, and supports multiple themes, viewports, media settings, and other global combinations through modes. It can also publish a temporary Storybook for sharing. The package is an integration layer over the `chromatic` CLI and service, not a local screenshot-diff engine or a general unit-test runner.
The smoothest Storybook-native route to Chromatic's hosted visual review if the account, service boundary, and Storybook 10 requirement fit. Skip it for offline baselines, Node 18, older Storybook majors, or teams whose real need is behavioral or accessibility testing.
Use it if
- Your component team already uses Storybook 10.1 or newer and wants visual results inside the Storybook interface
- You want hosted baseline storage, browser capture, review, and team approval rather than maintaining screenshot infrastructure
- You need one story captured across themes, locales, viewports, forced-colors, print, or reduced-motion modes
- You want designers and reviewers to inspect changed stories or a quickly shared Storybook without checking out the branch
- You cannot send stories or snapshots to a hosted vendor: the README requires a configured Chromatic account with project access, and this addon talks to Chromatic's GraphQL service
- Your project is still on Storybook 9 or older: package 5.3.0 peers only with Storybook 10.1 and later 10.x lines; the changelog maps addon 4.x to Storybook 9 and 3.x to Storybook 8.2
- You run Node 18: version 5.3.0 declares Node.js 20 or newer, so installing it can force a runtime upgrade even if the application itself still supports an older Node line
- You want fully local, offline visual diffs with files you own: the panel depends on Chromatic authentication, remote builds, and hosted baselines, while Loki is designed around local or self-managed screenshot comparison
- You only need behavior or accessibility assertions: this package adds visual-change review and brings the chromatic CLI plus other runtime dependencies, while Storybook's test runner or accessibility addon targets those narrower failures directly
Setup reality
The supported setup is `npx storybook add @chromatic-com/storybook`, which installs the package and edits the Storybook configuration. A manual install also needs `@chromatic-com/storybook` in the `addons` array of `.storybook/main.ts`. Version 5.3.0 requires Node.js 20 or newer and declares `storybook` 10.1 through the supported 10.x prerelease ranges as its peer, so an older Storybook project must select the matching addon major rather than accept a forced peer override. The README's generic statement that Storybook 7.6 or later is enough is stale for the current package; the actual peer range and changelog are the safer compatibility sources. This is not a credential-free local test tool. The prerequisites require a Chromatic account with access to a project, and the panel walks users through browser authentication before it can announce and upload builds. CI usage typically needs the Chromatic CLI's project configuration or token kept in the CI secret store, never embedded in story files or committed config. The addon depends on `chromatic` 18.x and contacts the hosted service, so offline development cannot create or compare a new baseline. The apparent zero-config experience assumes Storybook already builds cleanly, Git metadata identifies the branch and commit, the service can reach all rendered assets, and stories settle into deterministic output. Fonts, dates, random IDs, animation, network data, and late layout shifts otherwise become noisy diffs. The story-level `parameters.chromatic` object can add `delay`, `ignoreSelectors`, `diffThreshold`, media emulation, cropping, and modes; `viewports` is now deprecated in favor of modes. Use delays sparingly because they slow every capture, mask application readiness bugs, and still do not make random output deterministic. The package includes CommonJS and ESM exports plus types, but it is a Storybook addon rather than an import used by application runtime code. Older Yarn 1 installs can hit the README's `ERR_REQUIRE_ESM` problem through string-width; the documented workaround pins `jackspeak` 2.1.1 via resolutions, while upgrading Yarn or using npm or pnpm is cleaner. Quick Share uploads a Storybook and may produce an expiring link, so teams should treat it as external publication and review what stories expose before clicking share.
Patterns
Install and configure through the Storybook CLIinstall-addon
npx storybook add @chromatic-com/storybookFor version 5.3.0, run this in a Storybook 10.1 or newer project on Node.js 20 or newer.
Add the addon manuallyconfigure-manually
// .storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';
const config: StorybookConfig = {
stories: ['../src/**/*.stories.@(ts|tsx)'],
addons: ['@chromatic-com/storybook'],
};
export default config;Use the Storybook framework package that matches the project; the addon belongs in `addons`, not application imports.
Exclude one story from visual snapshotsdisable-story-snapshot
export const LiveClock = {
parameters: {
chromatic: { disableSnapshot: true },
},
};This keeps the story available in Storybook but tells Chromatic not to capture it; use it for inherently nondeterministic stories.
Disable snapshots for every story in a filedisable-component-snapshots
const meta = {
component: StreamingChart,
parameters: { chromatic: { disableSnapshot: true } },
};
export default meta;Parameters on the default story metadata apply to all stories unless a story overrides them.
Capture light and dark theme modescapture-multiple-modes
export const ButtonModes = {
parameters: {
chromatic: {
modes: {
light: { theme: 'light' },
dark: { theme: 'dark' },
},
},
},
};Mode keys inside each object must match globals defined by the Storybook preview, such as a `theme` global provided by a decorator or addon.
Delay a snapshot for late renderingwait-before-capture
export const LoadedProfile = {
parameters: {
chromatic: { delay: 500 },
},
};Delay is milliseconds and slows every capture of the story; deterministic loaders or play functions are preferable when available.
Mask dynamic regions during comparisonignore-dynamic-elements
export const Dashboard = {
parameters: {
chromatic: {
ignoreSelectors: ['[data-live-clock]', '.random-avatar'],
},
},
};Matching elements are painted with a neutral color before comparison, so do not mask regions whose visual state is part of the requirement.
Tune the visual difference thresholdadjust-diff-threshold
export const CanvasChart = {
parameters: {
chromatic: { diffThreshold: 0.1 },
},
};The typed range is 0 to 1, with 0 most accurate and 1 least accurate; the documented default is 0.063.
Stop ignoring anti-aliased pixel differencesinclude-antialiasing-diffs
export const TypographySpecimen = {
parameters: {
chromatic: { diffIncludeAntiAliasing: true },
},
};The default is false. Enabling this makes font-rendering differences more visible and can also make baselines noisier across browsers.
Capture the reduced-motion presentationtest-reduced-motion
export const ReducedMotionMenu = {
parameters: {
chromatic: { prefersReducedMotion: 'reduce' },
},
};The accepted values are `reduce` and `no-preference`; this sets the media feature for the capture rather than rewriting component props.
Capture print media stylestest-print-styles
export const PrintableInvoice = {
parameters: {
chromatic: { media: 'print' },
},
};The current exported type accepts `print`; keep a normal screen story as well if both presentations require review.
Crop a snapshot to its viewportcrop-to-viewport
export const MobileDialog = {
parameters: {
chromatic: { cropToViewport: true },
},
};Use modes to vary viewport globals; the older numeric `viewports` array remains typed but is deprecated.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| chromatic | npm | Choose the CLI directly when visual builds belong in CI and the in-Storybook Visual Tests panel is unnecessary |
| loki | npm | Choose it when local or self-managed Storybook screenshot diffs matter more than hosted review and browser infrastructure |
| @storybook/test-runner | npm | Choose it when the primary requirement is automated story and play-function assertions rather than pixel baselines |
| @storybook/addon-a11y | npm | Choose it when the failure class is WCAG accessibility violations, which visual comparison does not reliably detect |