Image Dithering
A configurable image dithering filter for limited-color, pixelated, and retro treatments.
Customize
Installation
pnpm dlx shadcn@latest add @vivid-layer/image-ditheringUsage
Give the parent element an explicit size. image is required and accepts a
project-owned URL or an HTMLImageElement.
import { ImageDithering } from "@/components/effects/image-dithering"
export function ImageDitheringExample() {
return (
<div className="h-96 overflow-hidden rounded-xl">
<ImageDithering image="/images/your-image.webp" />
</div>
)
}The installable example uses a vivid-layer-hosted image and needs network access after installation. The core component embeds no asset and works with a consumer-owned local image.
API reference
The wrapper adds playback and runtime safeguards while preserving the
complete Paper ImageDithering API. See the
Paper Image Dithering reference
for the full prop table and accepted ranges.
| Prop | Type | Default | Description |
|---|---|---|---|
image | string | HTMLImageElement | required | Supplies the source image processed by the dithering shader. |
playback | "auto" | "always" | "paused" | "auto" | Controls motion policy. Auto pauses for reduced motion and while the shader is outside the viewport. |
width / height | number | string | "100%" | Sets the canvas CSS dimensions. Size the parent element to establish the visible area. |
maxPixelCount | number | 2073600 | Caps the rendered pixel budget. Override only after measuring the target devices. |
Accessibility
The shader is decorative by default: it is hidden from assistive technology and does not receive pointer events. Do not use the processed image as the only way to communicate essential information, and verify overlaid text contrast.
playback="auto" honors reduced motion by rendering a stable frame.
Performance
The default maxPixelCount limits rendering to approximately 1080p, and
automatic playback pauses work once the component is more than 200px outside
the viewport. Use appropriately sized source images and static posters in
dense component grids.
Loading and failure behavior
The component keeps its sized container visually empty during server rendering, image loading, and when WebGL2 is unavailable. A failed image request also leaves the container empty; the unprocessed source image is never exposed.
Credits
The rendering engine is Paper Shaders, distributed under the Apache License 2.0. The example image is Scott Webb's Banff landscape, released under CC0. vivid-layer supplies the adapter, playback and loading policies, documentation, and Registry packaging.
