Skip to documentation content
|

Dither

Dither images or animated procedural waves with configurable color and pattern controls.

dither-demo

Overview

Dither applies ordered, halftone, noise, or crosshatch patterns to images and procedural waves. Both sources share the same pixelation, tone, inversion, quantization, and palette controls.

The playground uses free Unsplash photographs by Martin Péchy and Marc Wieland.

Installation
npm install honestui

Usage

Procedural waves

import { DitherShader } from "honestui/shaders"

<DitherShader
  className="h-80 rounded-xl"
  sourceMode="waves"
  waveColor="#a5f3fc"
  waveFrequency={3}
  enableMouseInteraction
/>

Wave mode animates by default. Set animated={false} to render a static field.

Image

<DitherShader
  alt="Blue and orange apartment buildings against a clear sky."
  className="h-80 rounded-xl"
  colorMode="duotone"
  primaryColor="#111827"
  secondaryColor="#f97316"
  src="https://images.unsplash.com/photo-1553933420-77617bac448e?auto=format&fit=crop&w=1600&q=85"
/>

Remote image hosts must allow cross-origin image use so the canvas can read its pixels. Use a same-origin image when you control the asset pipeline. Larger canvases and smaller grid cells require more work, especially when animation is enabled.

Accessibility

In image mode, write alt text for the image's purpose and context; use an empty string when the image is decorative. The source image provides the accessible content and remains visible if canvas processing fails. Wave mode is decorative, its pointer interaction is optional, and animation stops when the user enables reduced motion.

API Reference
PropTypeDefaultDescription
sourceModeimage|waves"image"Selects an image or procedural wave field as the dither source.
srcstring–Image URL used by the canvas and fallback image. Required in image mode.
altstring–Alternative text for the image. Required in image mode; use an empty string for decorative images.
gridSizenumber4Size of each dithering grid cell.
ditherModebayer|halftone|noise|crosshatch"bayer"Pattern used to calculate the dither threshold.
colorModeoriginal|grayscale|duotone|custom"original"Method used to color the output.
invertbooleanfalseInverts the output colors.
pixelRationumber1Multiplier applied to the rendered pixel size.
colorCountnumber4Channel levels retained in original color mode.
primaryColorstring"#000000"Dark color used in duotone mode.
secondaryColorstring"#ffffff"Light color used in duotone mode.
customPalettestring[]["#000000", "#ffffff"]Two or more colors used in custom mode.
brightnessnumber0Brightness adjustment from -1 to 1.
contrastnumber1Contrast adjustment where 1 preserves the source contrast.
backgroundColorstring"transparent"Color shown behind transparent source pixels.
objectFitcover|contain|fill|none"cover"How the source image fits the canvas.
thresholdnumber0.5Bias applied to the dither threshold.
animatedboolean–Animates patterns that vary over time. Defaults to true for waves and false for images.
animationSpeednumber0.02Amount added to the animation time each frame.
waveSpeednumber0.05Travel speed of the procedural wave field.
waveFrequencynumber3Frequency multiplier between wave octaves.
waveAmplitudenumber0.3Amplitude multiplier between wave octaves.
waveColorstring"#808080"Base color of the procedural wave field.
enableMouseInteractionbooleantrueLets the pointer reshape the procedural wave field.
mouseRadiusnumber1Radius of pointer influence in normalized canvas units.
classNamestring–Class for sizing and styling the container.