halftone-webgl

GPU-accelerated halftone effects for the web. Lightweight, interactive, Webflow-friendly.

Features

• GPU-powered — Fragment-shader halftone math, runs entirely on the GPU
• 6 dot shapes — circle, square, diamond, line, cross, ellipse
• 4 color modes — mono, auto (source colors), CMYK separation, duotone
• 10 mouse interactions — reveal, magnify, warp, ripple, vortex, colorShift, focus, comet, sparkle
• Any source — static images, video, webcam, or no source at all
• Content overlay — Children are auto-promoted above the canvas; buttons/links pause interaction on hover
• Zero-config — Works with just data attributes, no JavaScript required
• ~21 KB gzipped (includes OGL WebGL abstraction)

Quick Start (CDN)

Add a script tag and use data attributes — no build step needed.

<script src="https://unpkg.com/halftone-webgl/dist/halftone-webgl.min.js"></script>

<div data-hwgl-element
     data-hwgl-source="photo.jpg"
     data-hwgl-shape="circle"
     data-hwgl-color-mode="mono"
     data-hwgl-interaction="sparkle"
     style="width: 100%; height: 400px;">
  <h1>Your content here</h1>
</div>

The library auto-initializes on DOMContentLoaded for every element with data-hwgl-element.

Video Source

<div data-hwgl-element
     data-hwgl-source="video.mp4"
     data-hwgl-interaction="sparkle"
     style="width: 100%; height: 400px;">
</div>

Webcam Source

<div data-hwgl-element
     data-hwgl-source="webcam"
     data-hwgl-interaction="warp"
     style="width: 100%; height: 400px;">
</div>

Quick Start (npm)

npm install halftone-webgl

import HalftoneWebGL from 'halftone-webgl';

const ht = new HalftoneWebGL({
  container: '#my-element',
  source: 'photo.jpg',
  shape: 'circle',
  colorMode: 'mono',
  interaction: 'sparkle',
});

// Update options at runtime
ht.set('frequency', 60);
ht.set({ shape: 'diamond', colorMode: 'cmyk' });

// Load a new source
await ht.loadSource('video.mp4');

// Clean up
ht.destroy();

Data Attributes API

Every configuration option can be set via a data-hwgl-* attribute on the container element.

JavaScript API

Constructor

const ht = new HalftoneWebGL({
  container: '#my-element', // CSS selector or DOM element (required)
  source: 'photo.jpg',     // any config option can be passed here
  // ...
});

Methods

set(key, value) / set({ ... })

Update one or more configuration options at runtime.

ht.set('frequency', 60);
ht.set({ shape: 'diamond', colorMode: 'cmyk', contrast: 2.5 });

loadSource(src)

Load a new image, video, or webcam source. Returns a Promise.

await ht.loadSource('photo.jpg');       // image URL
await ht.loadSource('video.mp4');       // video URL
await ht.loadSource('webcam');          // webcam
await ht.loadSource(myVideoElement);    // HTMLVideoElement
await ht.loadSource(myImageElement);    // HTMLImageElement

resize()

Manually trigger a resize. Automatically called via ResizeObserver — you rarely need this.

pause() / resume()

Stop or start the animation loop.

ht.pause();
ht.resume();

snapshot(type?, quality?)

Capture the current frame as a data URL.

const dataUrl = ht.snapshot();                        // PNG
const dataUrl = ht.snapshot('image/jpeg', 0.92);      // JPEG at 92% quality

destroy()

Clean up all resources — stops animation, removes the canvas, releases video/webcam streams, clears event listeners.

ht.destroy();

Properties

Events

ht.on('ready', () => { /* first frame rendered */ });
ht.on('sourceload', () => { /* source texture loaded */ });
ht.on('resize', ({ w, h }) => { /* container resized */ });
ht.on('error', (err) => { /* something went wrong */ });

Configuration Reference

Screen

Dot

Tone

Color

Source

Interaction

Container

Content Overlay Pattern

Any children inside the halftone container are automatically promoted above the canvas:

<div data-hwgl-element data-hwgl-source="bg.jpg" data-hwgl-interaction="sparkle"
     style="height: 400px;">
  <!-- These sit above the halftone canvas automatically -->
  <h1>Heading</h1>
  <p>Paragraph text — fully selectable.</p>
  <button>Clickable button</button>
</div>

How it works:

• The canvas is injected with position: absolute; pointer-events: none
• Child elements get position: relative; z-index: 1
• Buttons, links, and [data-hwgl-pause] elements pause the interaction effect on hover so they're easy to click

Custom elements can opt into pause behavior:

<div data-hwgl-pause>This pauses interaction on hover</div>

Browser Support

Requires WebGL 1 — supported in all modern browsers (Chrome, Firefox, Safari, Edge).

License

MIT