astro-dither

Dither for Astro, based on Leo's dithercn.

Website (placeholder URL, deployment pending) · Docs · Examples · npm

Animated dither backgrounds, gradients and image effects for Astro. No React.

Features

• No React. Plain Astro components and one custom element. Nothing to hydrate.
• 19 effects in one registry: aurora, waves, plasma, silk, smoke, contours, ripples, metaballs, tunnel, retro-grid, starfield, eclipse, globe, gradient, glow, mesh, beams, noise, rise.
• Image dithering that keeps the real img and its alt text in the tree.
• One shared WebGL context for every ordered-dither surface on a page, so many tiles cost about the same as one.
• Pauses itself offscreen and in hidden tabs. Respects prefers-reduced-motion.
• Typed props per effect. Your editor lists only the settings an effect has.
• Copy-source CLI for projects that want the code in their own repo.

Install

Quick start

Any of the 19 effects works the same way:

Components

Effects

Every effect takes the same props: params (its own typed settings), palette (2 to 8 colours), cell, matrix (Bayer 2x2, 4x4, 8x8 or noise), speed, class. The full parameter tables are in the package README.

Copy the source

Prefer owning the code instead of a dependency? Copy the components into your project:

• npx astro-dither add aurora image globe copies several at once.
• --dir src/components/ui changes the target directory (default src/components/dither).
• --force overwrites existing files; without it, changed files are skipped.
• npx astro-dither list shows all six components.
• all copies everything, including the engine.

Relative imports and assets (like the globe's land mask) are followed automatically.

How it works

Each component renders a <dither-surface> element with its settings serialised into a data attribute at build time. A small custom element mounts in the browser, opens one WebGL2 context shared by every ordered-dither surface on the page, and draws each effect's GLSL field through a Bayer threshold matrix into the palette. DitherImage uses the same idea on an image texture, in its own context, and leaves the original img in place so alt text, readers and no-JS still work.

Browser support and accessibility

• Requires WebGL2. Where a surface cannot start it stays blank; DitherImage falls back to the plain img.
• Backgrounds render aria-hidden so screen readers skip them.
• prefers-reduced-motion gets a still frame: every surface draws its stillTime frame once and stops.
• IntersectionObserver and visibilitychange pause rendering offscreen and in hidden tabs.

Repository layout

Development

Requires Node 22.23.4 or newer (.nvmrc) and pnpm (packageManager pins 12.11.2).

Deploying the site

The site deploys to Vercel from the repo root. Import the GitHub repo and Vercel reads vercel.json: framework astro, install pnpm install --frozen-lockfile, build pnpm build, output site/dist. Nothing else to set. The production URL is picked up automatically for absolute OG tags; set SITE_URL only if you need to override it.

Releasing

1. Bump version in packages/astro-dither/package.json.
2. Add an entry to packages/astro-dither/CHANGELOG.md.
3. pnpm run ci should be green.
4. pnpm --filter astro-dither publish --access public.

Contributing

See CONTRIBUTING.md. Bug reports and feature requests go through GitHub issues; security reports through private vulnerability reporting.

Credits

• Paper Shaders for the shader shapes and the image filter.
• dithercn by Leo, which this project is based on.
• Starwind UI, Cult UI and Kibo UI for the site's buttons and snippets.

Licence

MIT, Screen 2026.