Placeholder Images for Storybook Stories

Published March 10, 2026

Storybook stories need images that are stable, branded, and sized exactly right for each component. Random URLs or dynamic content introduce flakiness into visual tests and make it harder to review designs. Deterministic placeholder images solve this by giving every story a consistent, labeled asset that never changes between runs.

Why placeholder images matter in Storybook

Component stories work best when every prop has a predictable value. Image sources are no exception. When a story pulls from an external CDN or a random generator, screenshots differ between builds — Chromatic flags them as changes even though the UI itself hasn't moved.

Deterministic placeholder images break this cycle. You generate a pack once, commit it to your repository, and every story references the same file path. Chromatic sees identical pixels in every baseline run, so only genuine component changes produce diffs.

Sizing placeholders to match your component variants

Each component variant typically expects a specific aspect ratio. A card thumbnail might be 16:9 at 320 px wide, while a hero banner fills 1600×900. Getting the sizes right prevents layout shifts in your story canvas and avoids accidental overflow or empty space.

PlacePack accepts a freeform list of dimensions so you can describe every variant in one session. Enter sizes like `320x180`, `800x450`, and `1600x900` for a responsive image component, then download the whole pack as a ZIP.

Adding labels to communicate component context

Unlabeled grey rectangles are hard to interpret in a component library. A placeholder labeled `Card / Thumbnail / 16:9` or `Hero / Dark / 1600×900` tells the next developer exactly what role the image plays without opening the story source.

The PlacePack text template supports `{w}`, `{h}`, `{label}`, and `{ratio}` tokens. Set a template like `{label} {w}×{h}` and add an alias per row — the resulting images carry meaningful names in both the preview and the downloaded filenames.

Color-coding states with per-item overrides

Storybook stories often cover multiple UI states: default, hover, loading, error, and success. Using the same grey square for all of them makes it easy to mix them up during review.

Add a background color override per size entry to distinguish states at a glance. For example, use slate for the default state, amber for a warning card, and red for an error scenario. The color is embedded in each image file, so your story docs and the exported ZIP both reflect the state hierarchy.

This is especially useful when building design-system token documentation — each token gets its own color swatch baked into the placeholder.

Committing placeholders to your repository

Once you have a ZIP, unzip it into a `__fixtures__/images/` directory at the root of your Storybook project. Reference the files with relative imports in your stories:

Keep the filenames stable — never rename them between builds. If you need to update a placeholder (for example, when a component's aspect ratio changes), regenerate only that size and replace the file. Chromatic will capture a new approved baseline for that story and leave the others untouched.

import heroImg from "../../__fixtures__/images/hero_1600x900.png";

export const Default = {
  args: {
    src: heroImg,
    alt: "Hero / Default / 1600×900",
  },
};

Keeping the generator preset shareable

When the component library grows, you will revisit these sizes. Store the PlacePack share URL in your project README or a `docs/placeholders.md` file so any team member can reopen the exact configuration — same dimensions, same colors, same text template — without having to reconstruct it from scratch.

The share URL encodes every field in the hash, so it works even without a backend. Opening the link in PlacePack restores the full session instantly.

FAQ — Frequently asked questions

Can I use SVG placeholders in Storybook?

Yes. Download the SVG format from PlacePack and import it the same way as PNG. SVG files are smaller and scale perfectly to any density, which is useful for retina story canvases.

How do I update a placeholder when a component is resized?

Reopen the PlacePack share URL, change the affected dimensions, regenerate, and replace only the files that changed. Chromatic will ask for approval on those stories and leave the rest untouched.

What size limits apply?

PlacePack supports base dimensions up to 4000 px and retina multipliers up to @4x. That covers every Storybook viewport including ultrawide and high-DPI configurations.

Related guides

• Placeholder Images for Design System Documentation →