ditherface

Tiny, dependency-free React dither components.

• No runtime dependencies (React is a peer dependency)
• Keyboard + screen-reader accessible defaults
• Respects prefers-reduced-motion

Install

npm i ditherface

Usage

import DitherFace from "ditherface";

export function DemoFace() {
  return (
    <DitherFace
      seed="ada-lovelace"
      className="h-72 w-72"
      animated
      dotScale={3}
    />
  );
}

import { Dither, DitherBackground } from "ditherface";

export function DemoBackground() {
  return (
    <DitherBackground
      className="h-72 w-full"
      animated
      dotScale={3}
      seed="marketing-hero"
      palette={["#3b82f6", "var(--brand-accent)", "--color-red-9"]}
    >
      <div style={{ position: "relative", zIndex: 1 }}>Content on top</div>
    </DitherBackground>
  );
}

export function DemoCanvas() {
  return <Dither className="h-56 w-full" pixelSize={2} colorNum={5} />;
}

Accessibility

• Dither defaults to role="img" with an accessible label.
• Keyboard controls when interaction is enabled: arrow keys move focus, Home resets.
• Use decorative for purely visual usage.

Dither Props

• seed?: string (default "ditherface")
• tones?: string | string[] (explicit CSS tone steps)
• palette?: string | string[] (select one deterministic base color from list)
• palette and tones accept CSS color values, CSS custom properties like --brand-accent, and var(--brand-accent, #3b82f6) fallbacks
• waveSpeed?: number (default 0.05)
• waveFrequency?: number (default 3)
• waveAmplitude?: number (default 0.3)
• waveColor?: [number, number, number] (default [0.5, 0.5, 0.5])
• colorNum?: number (default 4)
• pixelSize?: number (default 2)
• disableAnimation?: boolean (default false)
• enableMouseInteraction?: boolean (default true)
• mouseRadius?: number (default 1)
• decorative?: boolean (default false)
• ariaLabel?: string

DitherBackground Props

• animated?: boolean (default true)
• dotScale?: number (default 2)
• seed?: string (default "ditherface")
• tones?: string | string[]
• palette?: string | string[]
• children?: ReactNode
• ditherProps?: Omit<DitherFaceProps, ...> for extra face-renderer options

DitherBackground uses the same renderer as DitherFace (without face features), so both components match visually.

All standard <canvas> or <div> props are forwarded on each component.

DitherFace Props

• seed: string (required)
• animated?: boolean (default true)
• dotScale?: number
• tones?: string | string[]
• palette?: string | string[]
• ariaLabel?: string
• showFeatures?: boolean (default true)
• showEyes?: boolean (default true)
• compact?: boolean (default false)
• children?: ReactNode (optional overlay)

DitherFace is the package default export.