Storybook parameters reference for visual tests
The Storybook parameters UI Verify reads under parameters.uiVerify or parameters.chromatic: disableSnapshot, delay, modes, viewports and baselineImage.
UI Verify reads these parameters from your built Storybook when it renders a build, after Storybook merges project (.storybook/preview), component meta and story parameters. So a value set in the preview applies to every story, a value on meta to one file, and a value on a story to that story only. Nothing is passed on the command line: `uiverify upload` ships the build and the parameters travel inside it.
Parameter namespaces: uiVerify and chromatic
UI Verify reads two namespaces: parameters.uiVerify, its own, and parameters.chromatic, the Chromatic-compatible one, so an existing Chromatic config works unchanged. When both set the same key, uiVerify wins for that key. The merge is per top-level key: if both namespaces set modes, the uiVerify.modes object is used whole and the chromatic.modes entries are not mixed in.
Parameters UI Verify reads
| Key | Type / example | Effect |
|---|---|---|
disableSnapshot | boolean, true | The story is not rendered, diffed or billed. Only true counts. |
delay | number (ms), 300 | Extra wait after the story has settled and its play has finished, before the screenshot. Only a positive number applies. |
modes | { [name]: { viewport?, theme?, disable? } } | Renders the story once per mode, each against its own baseline. Replaces the default viewport for that story. See modes. |
viewports | array, [390, 1280] | Legacy: one capture per entry, a width or a named viewport. Ignored when modes is set. |
baselineImage | string, "design/pricing.png" | Declares a design image as the story's baseline. See design baselines. |
pauseAnimationAtEnd | boolean | Read, but has no per-story effect (see below). |
baselineImage takes a relative .png path inside your built Storybook (serve it from a staticDirs folder) or a data:image/png;base64,... URI. URLs, absolute paths and .. segments are ignored.
Mode entry fields
A mode entry is one capture variant inside modes. The mode's name is its identity, so renaming a mode starts a new baseline for it. Each entry takes three optional fields:
| Field | Accepted values | Effect |
|---|---|---|
viewport | 390, "390px", { width: 1440, height: 900 }, or a named viewport like "mobile1" | Sets the capture size. A name resolves against your Storybook viewport options (parameters.viewport.options). A missing axis uses the default size. |
theme | "dark", "light", "brand-dark" | Sets the theme:<value> Storybook global. light and dark also emulate prefers-color-scheme. Letters, digits, spaces, _ and - only. |
disable | true | Drops a mode the story would otherwise inherit, for example from its meta. |
A legacy viewports entry accepts the same forms as a mode's viewport. An entry UI Verify cannot parse, or a named viewport it cannot resolve, is dropped; if every entry is dropped, the story renders at the default size. In modes, by contrast, a mode whose viewport cannot be resolved is kept and renders at the default size. Each mode, and each legacy width, is its own billable snapshot, so declare only the variants that matter. See snapshot billing.
Example story with visual test parameters
import type { Meta, StoryObj } from "@storybook/react";
import { Pricing } from "./Pricing";
const meta = {
component: Pricing,
parameters: {
uiVerify: {
modes: {
"mobile light": { viewport: 390, theme: "light" },
"desktop dark": { viewport: { width: 1440, height: 900 }, theme: "dark" },
},
},
},
} satisfies Meta<typeof Pricing>;
export default meta;
type Story = StoryObj<typeof meta>;
// Captured in both modes from meta.
export const Monthly: Story = {};
// Both modes, plus a 300 ms wait before each screenshot.
export const Annual: Story = {
args: { billing: "annual" },
parameters: { uiVerify: { delay: 300 } },
};
// Kept in Storybook, never captured or billed.
export const Playground: Story = {
parameters: { uiVerify: { disableSnapshot: true } },
};Storybook merges story parameters into the meta ones, so Annual keeps both modes and adds the delay. Prefer fixing the cause of a late render over a fixed delay; see Fix flaky visual tests.
Parameters UI Verify does not read
Parameters outside the table above are not read under either namespace. These are the Chromatic ones you are most likely to have:
| Parameter | What happens instead |
|---|---|
diffThreshold, diffIncludeAntiAliasing | Not read. The diff threshold is set by UI Verify, the same for every story. |
pauseAnimationAtEnd | Read, no effect. Finite CSS and Web Animations are always captured at their final frame, and infinite ones are stopped. |
prefersReducedMotion | Not read. Reduced motion is always emulated (see below). |
cropToViewport, forcedColors, media | Not read. |
Storybook tags | Do not include or exclude a story from capture. Use disableSnapshot. |
Default viewport and device scale
The default capture viewport is 1280 x 800 CSS pixels at a device scale factor of 1, in the light color scheme. A story with no modes or viewports is captured once at that size. A mode or legacy entry that omits the width or height takes it from this default.
Does the play function run before the snapshot?
Yes. UI Verify waits for the story to render and for its play function (or Storybook 10 .test()) to finish, then applies delay if set, then takes the screenshot. The snapshot is the state the interaction leaves the story in, and a play that throws fails the story instead of being diffed. See interaction tests.
Is reduced motion emulated?
Yes. Every capture emulates prefers-reduced-motion: reduce. A story without a play function gets it from first paint. A story with one gets it only after play finishes, so the interaction test runs with the same motion settings as a plain Storybook run, and your reduced-motion CSS still applies to the screenshot.
Browsers for Storybook projects
Browser selection is a project setting, not a story parameter. Chrome (Chromium) always renders. A Storybook project can also turn on Firefox and Safari (WebKit) under the project's Capture & AI settings; each extra browser renders every story again with its own baselines, so it adds a full set of snapshots. Playwright and Vitest projects render in Chromium only, and custom-screenshot projects are not rendered at all: the uploaded images are diffed as they are.
Deterministic Storybook stories
Stop story diffs that come back changed without a real change.
Storybook visual testing without Chromatic
You can love Storybook and still want off Chromatic. Those are separate decisions. Keep every story exactly as it is, point a different tool at your built output, and keep your PR diff check.
Visual testing for agents
UI Verify captures your UI on every pull request and an AI judge tells an intended change from a real regression. See how it works.
Get started