@ivanalbizu/astro-webgl-hover

WebGL image hover effects for Astro with displacement transitions using Curtains.js and GSAP.

Installation

npm install @ivanalbizu/astro-webgl-hover

Usage

---
import { WebglHoverImages, WebglHoverImage } from '@ivanalbizu/astro-webgl-hover';
---

<WebglHoverImages>
  <WebglHoverImage
    texture0="/image-default.jpg"
    texture1="/image-hover.jpg"
    map="/displacements/displacement.jpg"
  />
</WebglHoverImages>

Components

`<WebglHoverImages>`

Container component that initializes the WebGL context. Wrap all your <WebglHoverImage> components inside this.

Props

Prop	Type	Default	Description
`durationIn`	`number`	`0.8`	Duration of hover-in animation (seconds)
`durationOut`	`number`	`0.8`	Duration of hover-out animation (seconds)
`easeIn`	`string`	`'power2.out'`	GSAP easing for hover-in
`easeOut`	`string`	`'power2.out'`	GSAP easing for hover-out
`intensity`	`number`	`1`	Displacement intensity
`displacementAngle`	`number`	`0`	Displacement direction (degrees)
`zoom`	`number`	`0`	Zoom amount on hover (0-1)
`imageRotation`	`number`	`0`	Image rotation on hover (degrees)
`noiseSpeed`	`number`	`0.5`	Noise animation speed
`noiseScale`	`number`	`6.0`	Noise texture scale
`rgbShiftIntensity`	`number`	`0`	RGB shift/chromatic aberration intensity
`debug`	`boolean`	`false`	Show debug panel (lil-gui)

`<WebglHoverImage>`

Individual image component with hover effect.

Props

Prop	Type	Required	Description
`texture0`	`string`	Yes	Default image URL
`texture1`	`string`	Yes	Hover image URL
`map`	`string`	Yes	Displacement map URL

All props from <WebglHoverImages> can also be passed to individual <WebglHoverImage> components to override the global settings.

Displacement Maps

The map prop accepts a grayscale image that controls the displacement effect. You can find free displacement maps at:

Grayscale displacement textures
Create your own using Photoshop/GIMP noise filters

Debug Mode

Enable debug={true} on <WebglHoverImages> to show a control panel where you can adjust all parameters in real-time.

<WebglHoverImages debug={true}>
  <!-- ... -->
</WebglHoverImages>

Advanced Usage

You can also import the library directly for more control:

import { initWebglHover, WebglHover } from '@ivanalbizu/astro-webgl-hover';

// Initialize manually
const instances = initWebglHover();

// Control individual instances
instances[0].setProgress(0.5);
instances[0].destroy();

Performance

The library includes several optimizations:

Fallback for low-performance devices
Render loop pauses when not animating
Debounced resize handler
Optimized mesh segments

Browser Support

Requires WebGL support. Falls back to static images on unsupported devices.

License

MIT