Skip to main content
A dithering image filter with support for 4 dithering algorithms and multiple color palettes (2-color, 3-color, and multicolor options), using either predefined colors or colors sampled from the original image.

​
Features

  • Multiple dithering algorithms (random, 2x2, 4x4, 8x8 Bayer matrices)
  • Custom color palettes (2-7 colors)
  • Original color preservation mode
  • Inverted luminance option
  • Adjustable pixel grid size
  • Retro/vintage aesthetic

​
Basic Usage

import { ImageDithering } from '@paper-design/shaders-react';

function App() {
  return (
    <ImageDithering
      image="/path/to/image.jpg"
      type="8x8"
      size={2}
      colorFront="#94ffaf"
      colorBack="#000c38"
      colorHighlight="#eaff94"
      colorSteps={2}
      originalColors={false}
      inverted={false}
    />
  );
}

​
Parameters

​
Visual Parameters

​
image
string | HTMLImageElement
required
Source image to apply the dithering effect to
​
type
'random' | '2x2' | '4x4' | '8x8'
default:"'8x8'"
Dithering algorithm type:
  • random: Random noise dithering
  • 2x2: 2×2 Bayer matrix (coarse pattern)
  • 4x4: 4×4 Bayer matrix (medium pattern)
  • 8x8: 8×8 Bayer matrix (fine pattern)
​
size
number
default:"2"
Pixel size of the dithering grid in screen pixels
​
colorFront
string
default:"'#94ffaf'"
Primary foreground color in hex, rgb, or rgba format
​
colorBack
string
default:"'#000c38'"
Background color in hex, rgb, or rgba format
​
colorHighlight
string
default:"'#eaff94'"
Secondary foreground color (set same as colorFront for classic 2-color dithering)
​
colorSteps
number
default:"2"
Number of color levels to use in the output. Higher values create smoother gradients.
​
originalColors
boolean
default:"false"
Use the original colors of the image instead of the custom color palette
​
inverted
boolean
default:"false"
Inverts the image luminance (doesn’t affect the color scheme)

​
Sizing Parameters

​
fit
'none' | 'contain' | 'cover'
default:"'cover'"
How to fit the shader into the canvas dimensions
​
scale
number
default:"1"
Overall zoom level of the graphics
​
rotation
number
default:"0"
Overall rotation angle in degrees
​
offsetX
number
default:"0"
Horizontal offset of the graphics center
​
offsetY
number
default:"0"
Vertical offset of the graphics center

​
Animation Parameters

​
speed
number
default:"0"
Animation speed multiplier (0 for static)
​
frame
number
default:"0"
Manual frame control for animation

​
Presets

The ImageDithering shader comes with several built-in presets:
  • Default: 8×8 dithering with custom 3-color palette
  • Noise: Random dithering with warm colors
  • Retro: 2×2 dithering preserving original colors
  • Natural: 8×8 dithering with original colors and 5 levels
import { ImageDithering, imageDitheringPresets } from '@paper-design/shaders-react';

function App() {
  return <ImageDithering {...imageDitheringPresets[0].params} image="/image.jpg" />;
}

​
Examples

​
Classic Two-Color Dithering

<ImageDithering
  image="/image.jpg"
  type="8x8"
  size={2}
  colorFront="#000000"
  colorBack="#ffffff"
  colorHighlight="#000000"
  colorSteps={1}
  originalColors={false}
/>

​
Retro Game Effect

<ImageDithering
  image="/image.jpg"
  type="2x2"
  size={3}
  colorFront="#eeeeee"
  colorBack="#5452ff"
  colorHighlight="#eeeeee"
  colorSteps={1}
  originalColors={true}
/>

​
Noise Effect

<ImageDithering
  image="/image.jpg"
  type="random"
  size={1}
  colorFront="#a2997c"
  colorBack="#000000"
  colorHighlight="#ededed"
  colorSteps={1}
/>

​
Natural Gradient

<ImageDithering
  image="/image.jpg"
  type="8x8"
  size={2}
  colorSteps={5}
  originalColors={true}
/>

​
Technical Details

​
Shader Uniforms (Vanilla JS)

When using the vanilla JavaScript API: 
import { DitheringTypes } from '@paper-design/shaders';

{
  u_type: DitheringTypes.random, // or 1
  u_pxSize: 2,
  u_colorFront: [r, g, b, a],
  u_colorBack: [r, g, b, a],
  u_colorHighlight: [r, g, b, a],
  u_colorSteps: 2,
  u_originalColors: false,
  u_inverted: false,
}

​
Dithering Types

  • random (1): Random noise pattern
  • 2x2 (2): Coarse 2×2 Bayer matrix
  • 4x4 (3): Medium 4×4 Bayer matrix
  • 8x8 (4): Fine 8×8 Bayer matrix

​
Color Modes

Custom Palette Mode (originalColors: false):
  • Uses colorFront, colorBack, and colorHighlight
  • colorHighlight is used for the brightest areas
  • colorSteps controls gradient smoothness
Original Colors Mode (originalColors: true):
  • Preserves image colors while applying dithering
  • colorSteps controls quantization levels
  • Color palette parameters are ignored

​
Performance Notes

  • Static shader (no animation by default)
  • Pixel-based rendering for crisp dithering
  • Performance scales with canvas size
  • Lower size values = more pixels = slower rendering
  • Bayer matrices (2×2, 4×4, 8×8) are faster than random