Skip to content

Picture

What a stored image shows while it loads, plus the pause control an animated image needs.

<p class="cap-muted">The first stands in for an image still on its way: its pixels are not here, so the stored tiny picture shows, drawn at the box's size and smoothed into a blur over the stored main color. The box is the image's own size from the start, so nothing moves when the pixels arrive.</p>
<div class="picture-sample-row">
  <figure id="pic-loading"><img class="has-lqip" src="./specimen/loading.svg" alt="A teal circle beside a teal panel on a dark ground" width="640" height="360" style="background-image:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAJCAIAAAC0SDtlAAAAJElEQVR42mOQIxEwkKlBxMMDjiAi3Hl5yIj2GuB66OYkGgYrALdYRrt0LNmsAAAAAElFTkSuQmCC);background-color:#1e1e1e"><figcaption>Loading: the placeholder</figcaption></figure>
  <figure id="pic-loaded"><img class="has-lqip" src="../prose-blocks/specimen/poster.svg" alt="A teal circle beside a teal panel on a dark ground" width="640" height="360" style="background-image:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAJCAIAAAC0SDtlAAAAJElEQVR42mOQIxEwkKlBxMMDjiAi3Hl5yIj2GuB66OYkGgYrALdYRrt0LNmsAAAAAElFTkSuQmCC);background-color:#1e1e1e"><figcaption>Loaded: the image paints over it</figcaption></figure>
  <figure id="pic-color"><img class="has-lqip" src="./specimen/loading.svg" alt="A teal circle beside a teal panel on a dark ground" width="640" height="360" style="background-color:#0b6e6e"><figcaption>A file with only its main color</figcaption></figure>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/picture.css";

Usage

import { Picture } from "capsomer/react/picture";

<Picture attrs={image} alt="Alex Rivera at the spring survey" className="cover" priority />
<Picture picture={pictureProps(image, { alt: "" })} eager />
<img class="has-lqip" src="/media/a.jpg?w=704" srcset="…" sizes="…" width="704" height="469" alt="…"
  loading="lazy" decoding="async"
  style="background-image:url(&quot;data:image/webp;base64,…&quot;);background-color:#3a5f6b">
<span class="cap-motion">
  <picture>
    <source type="image/avif" srcset="/media/a.gif?w=704&f=avif&still=1 704w" media="(prefers-reduced-motion: reduce)">
    <source type="image/webp" srcset="/media/a.gif?w=704&still=1 704w" media="(prefers-reduced-motion: reduce)">
    <source type="image/webp" srcset="/media/a.gif?w=704 704w">
    <img src="/media/a.gif?w=704" width="704" height="396" alt="…" loading="lazy" decoding="async">
  </picture>
  <img class="cap-motion-still" src="/media/a.gif?w=704&still=1" srcset="/media/a.gif?w=704&still=1 704w" width="704" height="396" alt="…" loading="lazy" decoding="async">
  <label class="cap-motion-toggle"><input type="checkbox" class="cap-motion-pause"> Pause</label>
</span>

Examples

An animated image with its pause control, playing and paused

<p class="cap-muted">Pause is a checkbox, so it works with no script. While it is checked the still shows in place of the moving picture; with the system set to reduce motion the still shows and the control is not needed.</p>
<div class="picture-sample-row">
  <figure id="motion-playing">
    <span class="cap-motion">
      <picture><source type="image/svg+xml" srcset="./specimen/still.svg" media="(prefers-reduced-motion: reduce)"><img src="./specimen/moving.svg" alt="A teal ball rolls from side to side along a line" width="640" height="360" loading="lazy" decoding="async"></picture>
      <img class="cap-motion-still" src="./specimen/still.svg" alt="A teal ball rolls from side to side along a line" width="640" height="360" loading="lazy" decoding="async">
      <label class="cap-motion-toggle"><input type="checkbox" class="cap-motion-pause"> Pause</label>
    </span>
    <figcaption>Playing</figcaption>
  </figure>
  <figure id="motion-paused">
    <span class="cap-motion">
      <picture><source type="image/svg+xml" srcset="./specimen/still.svg" media="(prefers-reduced-motion: reduce)"><img src="./specimen/moving.svg" alt="A teal ball rolls from side to side along a line" width="640" height="360" loading="lazy" decoding="async"></picture>
      <img class="cap-motion-still" src="./specimen/still.svg" alt="A teal ball rolls from side to side along a line" width="640" height="360" loading="lazy" decoding="async">
      <label class="cap-motion-toggle"><input type="checkbox" class="cap-motion-pause" checked> Pause</label>
    </span>
    <figcaption>Paused</figcaption>
  </figure>
</div>

API reference

Picture

PropTypeRequiredDoes
classNamestringThe image's own class: its size and fit.
prioritybooleanThe page's one LCP image: eager, fetchpriority high.
eagerbooleanAbove the fold but not the LCP (the rest of a grid's first row): eager, at normal priority.

Parts and data attributes

ClassIs
.cap-motionits own class
.cap-motion-pauseits own class
.cap-motion-stillits own class
.cap-motion-toggleits own class
.cap-picturethe root
StateRead from
:checkedthe platform
:focus-visiblethe platform

Accessibility

KeyDoes
TabReaches Pause
Space on PauseStops the animation and shows the still, or starts it again
  • Pause is a native checkbox named by its visible word; checked means stopped. The focus ring goes round the whole control.
  • The moving picture and its still carry the same alt text, and only one is ever displayed, so a screen reader reads it once.
  • The control is a surface pill with a strong border, so it reads on any picture and in forced colors.
  • Screen readers: no manual NVDA or VoiceOver run, by decision (2026-11-07); the automated browser checks and a front-end review stand in. Automated: see the site's Tests page.