Does Chromatic Capture Full-Page Screenshots or Only Story Viewports?
Chromatic captures the full rendered UI height by default. Learn when viewport settings affect the snapshot and how to clip it to a Storybook viewport.
Direct answer: Chromatic captures the full height of the rendered UI by default, even when you set a viewport height. In Storybook, set parameters.chromatic.cropToViewport: true to clip the snapshot to the configured viewport height. The snapshot is also cropped to the component’s bounding box, so this means the full rendered UI height of the story—not an unlimited screenshot of the entire browser page.
How Chromatic viewport capture works
A viewport controls the browser dimensions used to render a story. It does not automatically set the snapshot’s height limit. With the default capture behavior, a story taller than the viewport can still produce a snapshot containing its full rendered height. [Chromatic Modes viewport documentation]
Chromatic trims the snapshot to the component’s bounding box to remove surrounding negative space. The resulting capture reflects the rendered UI inside that boundary.
Configure a Storybook viewport-height crop
Use the Modes API to specify viewport dimensions, then enable cropToViewport for stories that should stop at the viewport height:
export const TallStory = {
parameters: {
chromatic: {
modes: {
desktop: {
viewport: {
width: 1200,
height: 800,
},
},
},
cropToViewport: true,
},
},
};Here, Chromatic renders the story at 1200 × 800 pixels and clips the capture to that viewport height. Use the actual story export and configuration structure from your Storybook setup; the example shows the relevant parameters.
What happens when the root is shorter or taller?
- Root taller than the selected height: with
cropToViewport: true, the part beyond the viewport height is clipped. - Root shorter than the selected height: the snapshot is trimmed to the root container’s intrinsic height.
- No viewport height specified: capture height follows the root container’s intrinsic height.
- Crop setting omitted or false: a specified viewport height does not, by itself, clip a taller rendered UI.
Choose between full-height and viewport-height snapshots
| Goal | Configuration | Result |
|---|---|---|
| Capture the full rendered story height | Leave cropToViewport off |
Chromatic captures the full rendered UI height by default, subject to the component bounding box and image limits. |
| Stop at a specific height | Set a viewport height and cropToViewport: true |
Content below the viewport height is clipped. |
| Use the story’s natural height | Do not specify viewport height | Capture follows the root container’s intrinsic height. |
Chromatic documents a default viewport of 1200 × 900 pixels when none is specified. That default browser viewport does not mean every snapshot is clipped to 900 pixels high: clipping requires the crop setting.
Use Modes for viewport height
The legacy Storybook chromatic.viewports API does not support setting height. Chromatic identifies Modes as its successor and recommends it for height control. If a configuration appears to set a viewport but you cannot specify its height, check whether it uses the legacy API. [Modes viewport documentation; legacy viewport documentation]
Vitest and Cypress integrations
Chromatic also supports viewport configuration in Vitest and Cypress. Those integrations capture at the viewport configured for the test. The Storybook parameters.chromatic.cropToViewport setting is documented for Storybook; do not assume the same syntax or crop behavior applies unchanged to test integrations. Configure the test viewport using the integration’s own setup and consult the relevant Chromatic integration documentation. [Chromatic documentation]
Capture limits and image dimensions
Chromatic documents viewport dimensions from 200 to 2560 pixels and a maximum of 25,000,000 pixels per snapshot. It also documents a 32,767-pixel rendering limit for Safari and Firefox image width or height. At device pixel ratio (DPR) 2.0, an image reaches that dimension limit at half the corresponding CSS-pixel dimension. Chromatic says it retries at DPR 1.0 when browser image limits are exceeded. Visual captures use DPR 2.0 starting with Capture 9, with a DPR 1.0 fallback when dimensions exceed Firefox or Safari limits. [viewport limits; snapshot documentation]
For very tall stories, consider whether a full-height snapshot is useful: it can include content far below the initial viewport and approach the pixel limit. Use a viewport crop when the behavior you need to review is specifically what fits in the visible area.
Troubleshooting
The snapshot is taller than the configured viewport
Cause: A viewport height controls rendering dimensions, but the default capture includes the full rendered UI height. Fix: In Storybook, set parameters.chromatic.cropToViewport: true and confirm a viewport height is configured.
The snapshot is shorter than the viewport
Cause: The root container’s intrinsic height is shorter than the selected viewport. With cropping enabled, Chromatic trims to the root’s height. Fix: Check the story’s root layout and content. If the desired content is missing, make sure it is rendered inside the component’s bounding box.
Changing chromatic.viewports does not set the height
Cause: The legacy API does not support height. Fix: Migrate the viewport configuration to Modes, which supports width and height.
A very tall capture fails or changes sharpness
Cause: The snapshot may exceed the maximum pixel count or browser image dimension limits. Chromatic documents retrying at DPR 1.0 when Safari or Firefox limits are exceeded, which can change image sharpness. Fix: Reduce the captured height or width, crop to the viewport where appropriate, and check that the snapshot stays within documented limits.
A Vitest or Cypress capture ignores Storybook crop settings
Cause: The documented integration behavior uses the viewport configured for the test, and Storybook parameter syntax is not guaranteed to transfer. Fix: Set the viewport in the test integration’s configuration and verify against its Chromatic documentation.
Or skip the browser setup
If your goal is to capture a website URL directly, ScreenshotNeo is a website screenshot API and MCP server. Its one-call API can return PNG, JPEG, WebP, or PDF; use the full-page option when you need lazy images loaded across the page, or target a single element with a CSS selector. The full-page behavior and crop rules above apply to Chromatic’s story snapshots; ScreenshotNeo is an option for URL-based website captures.
Example using cURL:
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 request options. Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.
FAQ
Does a viewport height always crop a Chromatic snapshot?
No. In Storybook, a viewport height alone does not clip a taller UI. Enable cropToViewport: true to clip to that height.
Does “full page” mean the whole browser document?
For Chromatic stories, think of it as the full rendered UI height within the component’s bounding box. It is not an unlimited screenshot of an entire browser page.
What if I need to compare only the visible area?
Set a viewport height and enable parameters.chromatic.cropToViewport: true in Storybook.
Can I set viewport height with the legacy API?
No. Use Modes when you need to configure both viewport width and height.
