data-mock prototype

Placeholder media via data attributes. Add data-mock to img, video, iframe, or canvas for instant placeholder boxes with X-pattern, presets, and photo service integration.

Overview

The data-mock attribute turns native media elements into placeholder boxes. CSS renders the visual (gray box, X-pattern) and JS generates a valid src to keep the element well-formed. Moving to production means replacing src and removing data-mock — no HTML restructuring.

Hero banner
<img data-mock width="400" height="300" alt="Hero banner">

How It Works

  1. CSS applies a gray background, dashed border, and diagonal X-pattern via gradients
  2. JS generates an inline SVG data URI as src (for <img>), poster (for <video>), srcdoc (for <iframe>), or draws on <canvas>
  3. The label text comes from the alt attribute (images), title (iframes), or aria-label (canvas)
  4. Named presets set aspect ratio and default dimensions via CSS — no width/height attributes needed

Attributes

Attribute Type Description
data-mock string Preset name (hero, card, avatar, etc.) or empty for generic placeholder. Special values: photo (picsum), placehold (placehold.co).
data-seed string Reproducible seed for the photo preset (picsum.photos). Same seed always returns the same image.
data-mock-init boolean Set automatically to prevent double-binding. Do not set manually.

Presets

Named presets set aspect-ratio and a default inline-size via CSS. Explicit width/height attributes override the JS dimensions used for SVG generation.

PresetAspect RatioDefault WidthUse Case
hero3:1100%Hero banners
card16:9400pxBlog/article cards
avatar1:148pxUser avatars (rounded)
product1:1400pxProduct images
thumbnail1:1150pxGrid thumbnails
logo4:1200pxBrand logos
og1200:630100%Open Graph images
banner728:90100%Ad banners
Hero banner Card image User avatar Thumbnail Logo
<img data-mock="hero" alt="Hero banner"> <img data-mock="card" alt="Featured article"> <img data-mock="avatar" alt="User photo"> <img data-mock="product" alt="Product image"> <img data-mock="thumbnail" alt="Gallery thumb"> <img data-mock="logo" alt="Company logo">

Photo Service

Use data-mock="photo" for realistic placeholder photos from picsum.photos. The image dimensions come from width and height attributes.

Add data-seed for reproducible results — the same seed always returns the same photo.

<img data-mock="photo" width="400" height="300" alt="Product shot"> <!-- Reproducible with data-seed --> <img data-mock="photo" width="400" height="300" data-seed="42" alt="Consistent photo">

Placehold.co

Use data-mock="placehold" for labeled placeholder images from placehold.co. The alt text is used as the label.

<img data-mock="placehold" width="400" height="300" alt="Labeled placeholder">

Video, Iframe, and Canvas

data-mock works on all media elements.

Video

Gets a poster attribute with an SVG placeholder showing a play icon and label. Defaults to 16:9 aspect ratio.

<video data-mock width="800" height="450" alt="Product demo"></video>

Iframe

Gets a srcdoc with a minimal HTML page showing a centered label. Defaults to 16:9 with min-height 300px.

<iframe data-mock width="600" height="400" title="Embedded map"></iframe>

Canvas

Draws the X-pattern and label directly on the canvas context. Defaults to 4:3 aspect ratio.

<canvas data-mock width="400" height="300" aria-label="Chart area"></canvas>

Inside Figure

Works inside <figure> and <picture> with no structural changes needed.

Team photo
Our engineering team
<figure> <img data-mock="card" alt="Team photo"> <figcaption>Our engineering team</figcaption> </figure>

Production Transition

Moving to production requires no HTML restructuring. Replace src and remove data-mock.

<!-- Prototype --> <img data-mock width="400" height="300" alt="Hero banner"> <!-- Production: replace src, remove data-mock --> <img src="/images/hero.webp" width="400" height="300" alt="Hero banner">

Styling

The placeholder colors use design tokens (--color-gray-200, --color-gray-400). Override them with element-scoped CSS.

/* Override placeholder colors */ img[data-mock] { background-color: oklch(95% 0.02 250); border-color: oklch(80% 0.02 250); }

Wireframe Integration

When inside a [data-wireframe] container, mock media automatically adapts to wireframe tokens (--wireframe-fill, --wireframe-stroke, --wireframe-border). No extra configuration needed.

Dynamic Elements

Elements added to the DOM after page load are automatically enhanced via a MutationObserver.

// Dynamically added mock elements are auto-enhanced via MutationObserver const img = document.createElement('img'); img.dataset.mock = 'card'; img.alt = 'Dynamic card'; document.body.appendChild(img); // img gets placeholder SVG automatically

Accessibility

  • Always include alt text on images — it doubles as the placeholder label
  • Use title on iframes and aria-label on canvas for labeling
  • The generated SVG includes role="img" and aria-label
  • Placeholder images get loading="lazy" for photo/placehold variants