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
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.
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
| Prop | Type | Default | What it does |
|---|---|---|---|
src | string | none | Required. URL of the underlying image to display and distort. |
alt | string | none | Required. Accessible alternative text for the image. |
width | number | string | none | Optional. No default. Layout width of the wrapper and the img. |
height | number | string | none | Optional. No default. Layout height of the wrapper and the img. |
strength | number | 0.25 | Displacement ripple magnitude on hover. |
speed | number | 1 | Frequency and wave propagation rate during interaction. |
maxTier | number | 3 | Hard ceiling on the capability tier (0 to 3). |
paused | boolean | false | Universal pause prop. Releases the WebGL context and shows the plain image; hover or focus does nothing until un-paused. |
crossOrigin | "anonymous" | "use-credentials" | "" | none | Optional. 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" | none | Optional. No default. Native fetchpriority attribute forwarded to the underlying img element. |
fetchpriority | "high" | "low" | "auto" | none | Optional. 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. |
srcSet | string | none | Optional. No default. Native srcset. When the browser picks another candidate (resize, DPR change) the new pixels are uploaded to the texture. |
sizes | string | none | Optional. No default. Native sizes attribute for srcSet. |
imgClassName | string | "" | Class names for the inner img. |
imgStyle | React.CSSProperties | none | Optional. No default. Inline styles merged onto the inner img. |
className | string | "" | Extra classes on the wrapper div. Other HTML div attributes (data-*, aria-*) are passed to the wrapper, not to the img. |
style | React.CSSProperties | none | Optional. No default. Inline styles on the wrapper div, merged after width and height (consumer wins). |
ref | React.Ref<HTMLDivElement> | none | Receives the wrapper <div> around the <img> (not the <img> itself). |
onPointerEnter | React.PointerEventHandler<HTMLDivElement> | none | Optional. No default. Composed: called first, then the component's own handling. onPointerMove, onPointerLeave, onFocus and onBlur are composed the same way. |
children | React.ReactNode | none | Optional. 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.
| Measure | Result |
|---|---|
| Size, gzip | 4.6 KB at load, 4.31 KB loaded later |
| Layout shift | 0 |
| Frames when nothing should move | off screen 0, hidden tab 0, reduced motion 0 |
| axe accessibility scan | 0 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.
| Environment | Tier | Result | Date | Notes |
|---|---|---|---|---|
| Chromium Desktop (SwiftShader) | 3 | pass | 2026-10-21 | 29 passed, 0 failed |
| Chromium Mobile (Pixel 7 emulation) | 2 | pass | 2026-10-21 | 26 passed, 0 failed |
| Firefox Desktop | 3 | pass | 2026-10-21 | 26 passed, 0 failed |
| WebKit Desktop | 3 | pass | 2026-10-21 | 24 passed, 0 failed |
| WebKit Mobile (iPhone 14 emulation) | 2 | pass | 2026-10-21 | 24 passed, 0 failed |
On different devices
Reduced motion (static): Renders the plain static image with no WebGL context and no animation frames.
| Tier | What it does |
|---|---|
| T3 Full | WebGL2 displacement overlay at DPR <= 2.0, full render scale, texture <= 2048px (fine pointer with hover) |
| T2 Standard | WebGL2 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 Lite | Plain image (coarse pointer with low-end hints) |
| T0 Static | Plain 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
styleattributes, so allowstyle-src-attr 'unsafe-inline'.