Vanilla Breeze

data-effect="animate-image"

Play/pause control for animated images. Add data-effect='animate-image' to any GIF, WebP, or APNG for a toggle button with automatic reduced-motion support.

Overview

The data-effect="animate-image" effect adds a play/pause toggle button to animated images. Users can stop distracting animations with a single click, and the image automatically pauses when prefers-reduced-motion is active.

This is part of the unified effects system. It ships in the effects pack.

How It Works

  1. The effect wraps the <img> in a .animate-image-wrapper container for positioning
  2. A toggle <button> is injected alongside the image
  3. On load, the first frame is captured to a canvas and converted to a static PNG data URL
  4. When paused, the image src is swapped to the static frame; when played, it reverts to the original animated source
  5. The data-animate-image-paused attribute tracks the paused state

Attributes

Attribute Type Description
data-effect="animate-image" string Activates animation control on an <img> element via the effects system.
data-animate-image-paused boolean Set initially to start the image paused. Also set/removed automatically when the user toggles playback.
data-effect-animate-image-init boolean Set automatically to prevent double-binding. Do not set manually.

Start Paused

Add data-animate-image-paused to the image to start it in a paused state. The first frame is captured on load and displayed as a static image until the user clicks play.

Reduced Motion

The effect automatically pauses animated images when the user has requested reduced motion. This is detected via two mechanisms:

  • prefers-reduced-motion: reduce — the OS-level media query
  • data-motion-reduced attribute on <html> — for app-level motion controls

When either is active, images are auto-paused after the first frame is captured. The user can still manually play the animation using the toggle button.

Runtime changes to the prefers-reduced-motion media query are also detected — if the user enables reduced motion while viewing the page, animated images will pause automatically.

Dynamic Elements

Images added to the DOM after page load are automatically enhanced via the effects system MutationObserver. No manual initialization is needed.
↑