ditherfx

image reveals for react. a picture starts as pure ink-on-paper dither, holds a beat, then resolves cell by cell into the real thing. halftone, bayer, noise and ascii patterns. canvas 2d, zero dependencies, a real img element underneath the whole time.

install

npm install @denizeffects/ditherfx

quick start

import { DitherReveal } from "@denizeffects/ditherfx";

<DitherReveal src="/photo.jpg" alt="a photo" />

by default the reveal plays when the image scrolls into view.

patterns

<DitherReveal src="/photo.jpg" mode="halftone" />  // ink dots sized by darkness
<DitherReveal src="/photo.jpg" mode="bayer" />     // ordered dither, woven retro grid
<DitherReveal src="/photo.jpg" mode="noise" />     // random grain, film-like
<DitherReveal src="/photo.jpg" mode="ascii" />     // glyphs by luminance

triggers

<DitherReveal src="/a.jpg" trigger="inview" />  // plays when scrolled into view (default)
<DitherReveal src="/a.jpg" trigger="mount" />   // plays immediately
<DitherReveal src="/a.jpg" trigger="hover" />   // re-dithers and resolves on pointer enter
<DitherReveal src="/a.jpg" play={n} />          // bump n to replay imperatively

loop mode

play forward, hold the image, dissolve back to dither, and repeat forever. good for index cards, previews, ambient galleries:

<DitherReveal src="/photo.jpg" loop />

the loop parks itself while offscreen and picks back up when scrolled into view.

still mode

skip the reveal and keep the dither forever. good for decorative art, hero backgrounds, section dividers:

<DitherReveal src="/photo.jpg" still />

props

| prop | type | default | notes | | --- | --- | --- | --- | | src | string | | same origin, or served with cors headers | | alt | string | "" | passed to the real img underneath | | mode | "halftone" \| "bayer" \| "noise" \| "ascii" | "halftone" | | | speed | "calm" \| "normal" \| "quick" | "normal" | | | trigger | "inview" \| "mount" \| "hover" | "inview" | | | play | number | 0 | bump it to replay | | cell | number | per mode | dot size in css px | | hold | number | 0.35 | fraction of the run spent as pure dither | | still | boolean | false | never resolves | | loop | boolean | false | forward, hold, reverse, forever | | ink | string | currentColor | dot color | | paper | string | transparent | ground behind the dots | | className, style | | | applied to the wrapper |

theming

:root {
  --dx-ink: #1b1a17;      /* dot color */
  --dx-paper: transparent; /* ground behind the dots */
}

with a transparent paper the dither sits directly on your page background, which is usually what you want.

how it works

the source image is sampled at cell resolution for luminance, drawn as a one bit dither on a canvas, and the true image is painted back cell by cell in bayer matrix order. when the run finishes the canvas hands off to the plain responsive img element that was underneath all along.

accessibility

the real img with its alt text is present from the first render, so screen readers and search engines never see the animation at all. under prefers-reduced-motion the finished image shows immediately and no canvas is created. cross origin images that cannot be sampled fall back to the plain image, never a broken frame.

license

mit