Image Dithering

Image Dithering is an image filter shader that posterizes an input image using ordered or random dithering algorithms. It supports predefined 2- and 3-color palettes as well as sampling colors directly from the original image, and exposes controls for dithering type, pixel size, and color step count.

This is an image filter shader — it requires an image input. In React, pass a URL string to the image prop and it is loaded automatically. In vanilla JS, pass a fully loaded HTMLImageElement to u_image.

Usage

React
Vanilla JS

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

export default function Example() {
  return (
    <ImageDithering
      image="/my-photo.jpg"
      type="8x8"
      size={2}
      colorFront="#94ffaf"
      colorBack="#000c38"
      colorHighlight="#eaff94"
      colorSteps={2}
      originalColors={false}
      inverted={false}
      style={{ width: 600, height: 400 }}
    />
  );
}

import { ShaderMount, imageDitheringFragmentShader, DitheringTypes } from '@paper-design/shaders';

const image = new Image();
image.crossOrigin = 'anonymous';
image.src = '/my-photo.jpg';

image.addEventListener('load', () => {
  const container = document.querySelector('#canvas-container');

  const shader = new ShaderMount(container, imageDitheringFragmentShader, {
    u_image: image,
    u_colorFront: [0.58, 1, 0.69, 1],
    u_colorBack: [0, 0.047, 0.22, 1],
    u_colorHighlight: [0.918, 1, 0.58, 1],
    u_type: DitheringTypes['8x8'],
    u_pxSize: 2,
    u_colorSteps: 2,
    u_originalColors: false,
    u_inverted: false,
  });
});

The HTMLImageElement must be fully loaded before passing it to ShaderMount. Listen for the load event as shown above.

Props

image

string (React) | HTMLImageElement (vanilla JS)

required

The source image to dither. In React, pass a URL string — the component loads it automatically. In vanilla JS, pass a fully loaded HTMLImageElement as u_image.

type

DitheringType

default:"'8x8'"

The dithering algorithm. Use the DitheringTypes enum (vanilla JS) or string literal (React).

Value	Description
`random`	Randomized threshold dithering
`2x2`	2×2 Bayer ordered dithering
`4x4`	4×4 Bayer ordered dithering
`8x8`	8×8 Bayer ordered dithering

size

number

default:"2"

Pixel size of the dithering grid in screen pixels. Range: 0.5 to 20.

colorSteps

number

default:"2"

Number of quantization levels applied to both color modes. Range: 1 to 7.

originalColors

boolean

default:"false"

When true, colors are sampled directly from the original image rather than using the colorFront / colorBack / colorHighlight palette.

inverted

boolean

default:"false"

Inverts the image luminance before dithering. Has no effect when colorSteps is at its minimum (zero contrast).

colorFront

string

default:"'#94ffaf'"

Foreground (dark) color used in the dithering palette when originalColors is false.

colorBack

string

default:"'#000c38'"

Background (light) color used in the dithering palette when originalColors is false.

colorHighlight

string

default:"'#eaff94'"

Secondary foreground color blended in at the brightest steps. Set equal to colorFront for classic 2-color dithering.

Presets

The following presets are exported from @paper-design/shaders-react:

Export	Name	Description
`defaultPreset`	Default	8×8 Bayer with a green/navy palette
`noisePreset`	Noise	Random dithering in monochrome
`retroPreset`	Retro	2×2 Bayer using original image colors
`naturalPreset`	Natural	8×8 Bayer in grayscale with 5 color steps

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

Enums

Import DitheringTypes from @paper-design/shaders when using the vanilla JS API:

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

// DitheringTypes: random | '2x2' | '4x4' | '8x8'

Get Started

Core Concepts

Shaders

Image Filters

Image Dithering

Usage

Props

Presets

Enums

Get Started

Core Concepts

Shaders

Image Filters

Documentation Index

​Usage

​Props

​Presets

​Enums

Usage

Props

Presets

Enums