How do I use placeholder images in Storybook stories?

Import the PNG file using require() or ES import, then pass it as the image prop in your story args. Committing the file to the repository ensures consistent output in every CI build.

Will Chromatic flag placeholder images as changed?

Only if the image file itself changes. As long as you commit the same placeholder file, Chromatic will see identical pixels and produce a stable baseline.

Can I use SVG placeholders in Storybook?

Yes. SVG files can be imported and used as image sources in Storybook. SVG placeholders are smaller and scale to any DPI, which is useful for retina story canvases.

Placeholder Images for Storybook

Storybook stories need images that are stable across every build. Dynamic URLs or external CDNs introduce variability that causes Chromatic to flag false diffs. This preset generates deterministic placeholder images for the most common Storybook component sizes — ready to commit as fixtures.

Size reference

Name	Dimensions	Description
hero	1600x900	Hero — 1600×900px (16:9), full-width component hero image
card	960x720	Card — 960×720px (4:3), card component media image
widget	640x360	Widget — 640×360px (16:9), dashboard and widget component image
state_default	1280x720	Default state — 1280×720px, baseline component state
state_hover	1280x720	Hover state — 1280×720px, secondary component state for interaction testing

Why these sizes matter

Chromatic's visual regression system compares screenshot pixels between builds. Any image that changes between builds — even slightly — is flagged as a diff. Committed placeholder images from this preset produce identical pixels in every Storybook build, so Chromatic only captures genuine component changes.

Use cases

Chromatic baseline stability

Commit placeholder images to your repository and import them in stories. Chromatic will capture a stable baseline that never changes unless you intentionally update the fixture.

Component state documentation

Use separate placeholder images for default and hover states (with different labels or colors) so each story variant is visually distinguishable in the Storybook component library.

Design system consistency

Ensure every component in your design system uses a placeholder at the documented image slot dimensions, making it easy to review sizing decisions across the library.

FAQ — Frequently asked questions

How do I use placeholder images in Storybook stories?: Import the PNG file using require() or ES import, then pass it as the image prop in your story args. Committing the file to the repository ensures consistent output in every CI build.
Will Chromatic flag placeholder images as changed?: Only if the image file itself changes. As long as you commit the same placeholder file, Chromatic will see identical pixels and produce a stable baseline.
Can I use SVG placeholders in Storybook?: Yes. SVG files can be imported and used as image sources in Storybook. SVG placeholders are smaller and scale to any DPI, which is useful for retina story canvases.

Ready to generate Storybook placeholder images?

Open the generator with this preset pre-loaded and download your pack in seconds.

Open Storybook in PlacePack →

PlacePack for Storybook & Chromatic Teams →Related guide →