Skip to content

media · WebGL

DistortionImage

Images that ripple like air above a flame when you hover them, and stay plain images everywhere else.

WebGL2 hover-displacement image overlay

  • WebGL
  • Reduced motion: static
  • 4.6 KB gzip
  • 4 WebGL contexts
  • Layout shift 0
View the source Spec sheet as Markdown

Install

Install
pnpm dlx shadcn@4.21.1 add @frictionborn/distortion-image

Playground

Hover or focus the image. On touch screens and with reduced motion it stays a plain image.

Your code
import { DistortionImage } from "@/components/ui/distortion-image";

<DistortionImage
  src="/images/field.webp"
  alt="Describe the image"
  width={420}
  height={300}
 />

In a full example

The full example loads as you scroll to it.

Accessibility

  • The underlying HTML img element keeps the full accessible name via alt; the WebGL canvas overlay and focus ring are aria-hidden. A linked image gets exactly one tab stop (the link itself). Keyboard activation is supported whether the image is wrapped in an <a> or contains a covering <a> inside its children.
  • Keyboard: The wrapper is not focusable. For linked images (wrapped in <a> or containing a covering <a>), focus on the link triggers the ripple on fine-pointer devices and draws a two-tone inset focus ring above the canvas, inside the image box so parent overflow:hidden cannot clip it; exactly one tab stop is preserved. Purely decorative images have no keyboard activation. The canvas is aria-hidden
  • Touch: Touch pointers fall back to the plain static image with zero WebGL allocation
  • WCAG criteria it is built for: 1.1.1, 2.2.2, 2.3.1

Props

PropTypeDefaultWhat it does
srcstringnoneRequired. URL of the underlying image to display and distort.
altstringnoneRequired. Accessible alternative text for the image.
widthnumber | stringnoneOptional. No default. Layout width of the wrapper and the img.
heightnumber | stringnoneOptional. No default. Layout height of the wrapper and the img.
strengthnumber0.25Displacement ripple magnitude on hover.
speednumber1Frequency and wave propagation rate during interaction.
maxTiernumber3Hard ceiling on the capability tier (0 to 3).
pausedbooleanfalseUniversal pause prop. Releases the WebGL context and shows the plain image; hover or focus does nothing until un-paused.
crossOrigin"anonymous" | "use-credentials" | ""noneOptional. No default. CORS setting for the image. Only set to 'anonymous' when the host server sends Access-Control-Allow-Origin headers. If set on a host without CORS headers, the browser blocks the image entirely. When omitted, images from non-CORS hosts cleanly fall back to static image display without errors.
fetchPriority"high" | "low" | "auto"noneOptional. No default. Native fetchpriority attribute forwarded to the underlying img element.
fetchpriority"high" | "low" | "auto"noneOptional. No default. Lower-case alias of fetchPriority, used only when fetchPriority is not set.
loading"eager" | "lazy""lazy"Native browser image loading attribute.
decoding"async" | "auto" | "sync""async"Native browser image decoding behavior.
srcSetstringnoneOptional. No default. Native srcset. When the browser picks another candidate (resize, DPR change) the new pixels are uploaded to the texture.
sizesstringnoneOptional. No default. Native sizes attribute for srcSet.
imgClassNamestring""Class names for the inner img.
imgStyleReact.CSSPropertiesnoneOptional. No default. Inline styles merged onto the inner img.
classNamestring""Extra classes on the wrapper div. Other HTML div attributes (data-*, aria-*) are passed to the wrapper, not to the img.
styleReact.CSSPropertiesnoneOptional. No default. Inline styles on the wrapper div, merged after width and height (consumer wins).
refReact.Ref<HTMLDivElement>noneReceives the wrapper <div> around the <img> (not the <img> itself).
onPointerEnterReact.PointerEventHandler<HTMLDivElement>noneOptional. No default. Composed: called first, then the component's own handling. onPointerMove, onPointerLeave, onFocus and onBlur are composed the same way.
childrenReact.ReactNodenoneOptional. No default. Content layered above the image and canvas, for example a caption or a link.

Measured on the bench

Measured by the automated bench at commit 801163e on 2026-10-21. These numbers are written by the bench, never by hand.

MeasureResult
Size, gzip4.6 KB at load, 4.31 KB loaded later
Layout shift0
Frames when nothing should moveoff screen 0, hidden tab 0, reduced motion 0
axe accessibility scan0 serious, 0 critical

Browsers it ran in

Automated Playwright runs, some with device emulation. Results from physical phones and tablets are still pending, so none are listed.

EnvironmentTierResultDateNotes
Chromium Desktop (SwiftShader)3pass2026-10-2129 passed, 0 failed
Chromium Mobile (Pixel 7 emulation)2pass2026-10-2126 passed, 0 failed
Firefox Desktop3pass2026-10-2126 passed, 0 failed
WebKit Desktop3pass2026-10-2124 passed, 0 failed
WebKit Mobile (iPhone 14 emulation)2pass2026-10-2124 passed, 0 failed

On different devices

Reduced motion (static): Renders the plain static image with no WebGL context and no animation frames.

TierWhat it does
T3 FullWebGL2 displacement overlay at DPR <= 2.0, full render scale, texture <= 2048px (fine pointer with hover)
T2 StandardWebGL2 displacement overlay at DPR <= 1.5, 0.75 render scale, texture <= 1024px, only when the device reports (hover: hover) and (pointer: fine); coarse-pointer devices at this tier get the plain image
T1 LitePlain image (coarse pointer with low-end hints)
T0 StaticPlain image, no WebGL (server render, prefers-reduced-motion, Save-Data, no WebGL2, or frame-guard downgrade)

Content Security Policy

  • Works without 'unsafe-eval'.
  • Needs no reveal gate.
  • Sets inline style attributes, so allow style-src-attr 'unsafe-inline'.

Goes well with