# Dither

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

Source: https://www.honestui.com/docs/shaders/dither

---
title: Dither
description: Dither images or animated procedural waves with configurable color and pattern controls.
---

<ComponentPreview name="dither-demo" playground />

## 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](https://unsplash.com/photos/blue-and-orange-building-faPvxns9O70) and [Marc Wieland](https://unsplash.com/photos/sunset-over-a-serene-mountain-lake-1Kcgpq1ap9E).

## Installation

### npm

```bash
npm install honestui
```

### yarn

```bash
yarn add honestui
```

### bun

```bash
bun add honestui
```

### pnpm

```bash
pnpm add honestui
```

## Usage

### Procedural waves

```tsx
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

```tsx
<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


  ### `sourceMode`

type: `"image" | "waves"` · default: `"image"`

Selects an image or procedural wave field as the dither source.
  ### `src`

type: `string`

Image URL used by the canvas and fallback image. Required in image mode.
  ### `alt`

type: `string`

Alternative text for the image. Required in image mode; use an empty string for decorative images.
  ### `gridSize`

type: `number` · default: `4`

Size of each dithering grid cell.
  ### `ditherMode`

type: `"bayer" | "halftone" | "noise" | "crosshatch"` · default: `"bayer"`

Pattern used to calculate the dither threshold.
  ### `colorMode`

type: `"original" | "grayscale" | "duotone" | "custom"` · default: `"original"`

Method used to color the output.
  ### `invert`

type: `boolean` · default: `false`

Inverts the output colors.
  ### `pixelRatio`

type: `number` · default: `1`

Multiplier applied to the rendered pixel size.
  ### `colorCount`

type: `number` · default: `4`

Channel levels retained in original color mode.
  ### `primaryColor`

type: `string` · default: `"#000000"`

Dark color used in duotone mode.
  ### `secondaryColor`

type: `string` · default: `"#ffffff"`

Light color used in duotone mode.
  ### `customPalette`

type: `string[]` · default: `["#000000", "#ffffff"]`

Two or more colors used in custom mode.
  ### `brightness`

type: `number` · default: `0`

Brightness adjustment from -1 to 1.
  ### `contrast`

type: `number` · default: `1`

Contrast adjustment where 1 preserves the source contrast.
  ### `backgroundColor`

type: `string` · default: `"transparent"`

Color shown behind transparent source pixels.
  ### `objectFit`

type: `"cover" | "contain" | "fill" | "none"` · default: `"cover"`

How the source image fits the canvas.
  ### `threshold`

type: `number` · default: `0.5`

Bias applied to the dither threshold.
  ### `animated`

type: `boolean`

Animates patterns that vary over time. Defaults to `true` for waves and `false` for images.
  ### `animationSpeed`

type: `number` · default: `0.02`

Amount added to the animation time each frame.
  ### `waveSpeed`

type: `number` · default: `0.05`

Travel speed of the procedural wave field.
  ### `waveFrequency`

type: `number` · default: `3`

Frequency multiplier between wave octaves.
  ### `waveAmplitude`

type: `number` · default: `0.3`

Amplitude multiplier between wave octaves.
  ### `waveColor`

type: `string` · default: `"#808080"`

Base color of the procedural wave field.
  ### `enableMouseInteraction`

type: `boolean` · default: `true`

Lets the pointer reshape the procedural wave field.
  ### `mouseRadius`

type: `number` · default: `1`

Radius of pointer influence in normalized canvas units.
  ### `className`

type: `string`

Class for sizing and styling the container.