Liquid Marble
An interactive WebGL component applying a fluid chromatic distortion that clears into a crystal lens around the cursor.
Last Modified:Aug 17, 2026
Install
CLI
liquid-marble
Or install a specific demo variant:
liquid-marble-image
Or install a specific demo variant:
liquid-marble-video
Manual
1. Install Dependencies
Since this component leverages WebGL, you will need React Three Fiber and Three.js.
CLI Install
Note: The demos utilize @hugeicons/react and @hugeicons/core-free-icons for the loading fallback, but they are not strictly required for the core component.
2. Add Source Code
Props
| Prop | Type | Default | Description |
|---|---|---|---|
mediaUrl | string | — | The source URL of the media asset. |
mediaType | "image" | "video" | "image" | Defines the media type for correct texture processing. |
hoverRadius | number | 0.35 | How wide the clarity lens spreads (0.0 to 1.0). |
distortionStrength | number | 0.1 | How violently the liquid swirls outside the cursor. |
noiseScale | number | 3.0 | Scale of the noise. Lower = larger, sweeping waves. Higher = tighter ripples. |
speed | number | 0.2 | How fast the liquid continuously flows over time. |
imageZoom | number | 1.2 | Internal zoom to prevent revealing image edges during heavy distortion. |
mouseLerpSpeed | number | 3.0 | Fluidity of the mouse tracking. Lower = heavier drag. |
enterLeaveSpeed | number | 1.5 | Speed at which the clarity lens fades in/out. |
fallback | React.ReactNode | null | Optional fallback UI rendered via Suspense while media loads. |
className | string | undefined | Standard React classNames for the container wrapper. |