dither-ui

npm version npm downloads npm license peer dependency React

Retro, IBM-PC-flavored ordered Bayer dither for React: full-width gradients and offset drop shadows drawn on canvas (no bitmap assets). Works with hex, rgb / rgba, transparent, and a built-in VGA 16-color name table.

Install

npm install dither-ui

Peer dependency: React 18 or 19.

Usage

Gradient

import { DitherGradient } from 'dither-ui';

<DitherGradient
  colors={['#1a2838', '#b8dcf8']}
  direction="to-bottom"
  minHeight={160}
  pixelScale={2}
  matrixSize={4}
/>

direction is one of to-bottom, to-right, or diagonal (top-left → bottom-right).

Drop shadow (DitherBox)

Wrap content; the library measures the child box and paints a down-right dithered shadow (depth in CSS px). Solid tint:

import { DitherBox } from 'dither-ui';

<DitherBox depth={16} shadowColor="#a8b0c0" pixelScale={2}>
  <div>Card</div>
</DitherBox>

Gradient shadow (same direction keywords as DitherGradient):

<DitherBox
  depth={16}
  shadowColors={['#5ec8e0', '#1a3a55']}
  shadowDirection="to-right"
  pixelScale={2}
>
  <div>Card</div>
</DitherBox>

VGA palette snap

Pass a custom palette (array of color strings), or set **vgaSnap** to use the bundled **VGA_16_HEX** list:

<DitherGradient colors={['#7ec8d4', '#263646']} vgaSnap />

Note: With a palette, gradients pick two endpoint swatches and ordered-dither between those two. Shadows blend your tint in RGBA, apply Bayer thresholding, then snap each surviving pixel to the nearest swatch — not the same inner loop as gradients. See JSDoc on DitherPixelProps.palette in the published types.

Color strings

[parseColor](src/color.ts) (exported) understands:

• Hex (#rgb, #rrggbb, #rrggbbaa)
• rgb() / rgba()
• transparent
• VGA names such as red, white, lightcyan, brightblue, …

Exports include VGA_16, VGA_16_HEX, VGA_NAMED_COLORS, and helpers like vgaColor / isVgaColorName.

Shared props

Types: DitherPixelProps (canvas + palette), DitherProps (gradient: colors, direction), DitherBoxProps (shadow: shadowColor, shadowColors, shadowDirection, …).

| Prop | Role | | ------------ | ------------------------------------------------------------------ | | pixelScale | Dither cell size in CSS px (default 2) | | matrixSize | 4 or 8 Bayer matrix | | depth | Shadow offset (DitherBox only; default 16) | | palette | Optional string[] to snap output | | vgaSnap | If true, use built-in VGA_16_HEX (ignored if palette is set) |

Lower-level utilities (gradientTAt, getOrderedThreshold, orderedDitherBetween, …) are exported for custom drawing.

Demo

From the repo root:

npm install
npm run demo

Builds the library, then starts the Vite demo (examples/demo). For demo dev only (after a one-time npm run build):

npm run demo:dev

Development

npm run build    # library → dist/
npm run dev      # watch mode for the library

TypeScript is strict; the package is ESM-first with a CJS build for require.

License

MIT