Applitools Eyes addon for Storybook

Run and triage visual tests inside the Storybook UI. Ideal for local development, design reviews, and quick feedback without leaving the component explorer.

If you're looking for our CLI version, please see our Quick Start Guide.

Requirements

• Applitools account & API key
• Storybook 8.6.14+

Install the addon

# One‑line, via Storybook CLI (recommended)
npx storybook add @applitools/eyes-storybook-addon

# Or manually
npm i -D @applitools/eyes-storybook-addon

# then add to main.ts
// .storybook/main.ts
module.exports = { addons: ['@applitools/eyes-storybook-addon'] }

Run Eyes setup (once per repo)

npx eyes-setup

Ensures applitools.config.js exists and your API key/server URL are configured.

Running tests in the UI

There are two ways to start a run:

• From the left sidebar test module → click Run (bottom-left).
• From the Applitools tab inside a story → click Run.

Either way, the addon runs Eyes for the current story (or as appropriate for your setup) and streams results back into the Applitools tab. Results include each configured browser/device from your applitools.config.js.

1. Start Storybook.
2. Open the Applitools tab for any component.
3. Click Run to execute visual tests for its stories. Results appear inline, including each configured browser/device.

Reviewing results (status & filtering)

After a run, the addon marks components/stories and shows an aggregated status count in the left sidebar test module:

• Green = passed
• Orange = unresolved (needs review)
• Red = failed

You can filter all results in the sidebar by clicking the status filter buttons (e.g., show only unresolved). This is useful when scanning a big Storybook to focus just on changes.

Viewing story results (compare tools)

Open a story’s Applitools tab to see its latest results (grouped by each configured browser/device). Click any result row to expand the review tools:

• Diff Image – highlights differences between the Expected (baseline) and Actual (checkpoint) images.
• Actual Image – the checkpoint image captured in this run.
• Expected Image – the baseline image used for comparison.
• Side By Side – baseline and checkpoint shown next to each other.
• Slider – baseline and checkpoint overlaid with a draggable slider for subtle diffs.

Note: To view the Expected (baseline) image or approve/reject a test result, you must be signed in to your Applitools account in the same browser running Storybook. If you are not authenticated, the addon will prompt you to sign in.

Approving & rejecting results (per-result and bulk)

• Per-result: click Thumbs Up (approve) or Thumbs Down (reject) on an unresolved diffs row.
• Bulk review: open the Applitools tab ellipsis (⋯) menu and use **Review actions to approve/reject all results for this story or all stories in the current batch.

All review actions sync to your Eyes batch and update test status accordingly.

Configuration (view the settings the addon will use)

Open any story, click the ellipsis (⋯) menu in the Applitools tab, and choose Configuration. This shows the effective Eyes settings that the addon will use when it runs visual tests — handy for confirming your applitools.config.js (API key, server URL, browsers/devices, etc.). For additional options and supported browsers/devices, see Configuration and Browsers & devices docs.

Why this matters: what you see here is exactly what the addon will use during execution, removing guesswork.

Learn more about this Applitools Eyes UI Addon & the Storybook CLI SDK in our SDK documentation.