@dloss/dithered-image

Interactive dithered/stippled image effect for the web. Converts any raster image into a field of animated dots rendered on an HTML Canvas with cursor repulsion and click shockwaves.

Features

• Dot-based rendering -- Samples an image and renders it as a grid of small square dots
• Cursor repulsion -- Dots near the mouse are pushed away with physics-based animation
• Click shockwaves -- Clicking sends an expanding ring that displaces dots as it passes
• Spring-back easing -- Dots smoothly animate back to their home positions
• Inverted mode -- Carve the image out as negative space inside a rounded-rect field of dots
• Color preservation -- Optionally retain original per-pixel colors on each dot
• Framework-agnostic -- Works with vanilla JS or React (component and hook exports)
• Zero runtime dependencies -- Only peer-depends on React (optional)
• RSC-compatible -- React entry points include "use client" directive for Next.js / React Server Components
• Tree-shakeable subpath exports -- Import only what you need (/vanilla, /react, or everything)

Installation

# npm
npm install @dloss/dithered-image

# yarn
yarn add @dloss/dithered-image

# pnpm
pnpm add @dloss/dithered-image

# bun
bun add @dloss/dithered-image

Usage

The library ships three subpath exports so you only pull in what you need:

React Component

The simplest way to use the library in React:

import { DitheredImage } from "@dloss/dithered-image/react";

function App() {
  return (
    <DitheredImage
      src="/logo.png"
      invert
      style={{ width: 500, height: 500 }}
    />
  );
}

React Hook

For more control over the canvas element:

import { useDitheredImage } from "@dloss/dithered-image/react";

function Logo() {
  const canvasRef = useDitheredImage("/logo.png", { invert: true });
  return <canvas ref={canvasRef} style={{ width: 500, height: 500 }} />;
}

Vanilla JavaScript

No React dependency -- attach the effect to any <canvas> element:

import { createDitheredCanvas } from "@dloss/dithered-image/vanilla";

const canvas = document.querySelector("canvas")!;
const cleanup = createDitheredCanvas(canvas, "/logo.png", {
  invert: true,
  gridSize: 200,
});

// Call cleanup() to remove event listeners and stop animation

Note: The root import (@dloss/dithered-image) re-exports everything for backwards compatibility, but includes React as a dependency. Use the subpath imports above to keep your bundle minimal.

Options

All options are optional. Pass them as props to <DitheredImage>, as the second argument to useDitheredImage, or as the third argument to createDitheredCanvas.

Shockwave Options

License

MIT