Overview
LiquidWave runs a real-time fluid simulation on a WebGL canvas using Three.js — computing advection, divergence, pressure, and viscosity passes every frame. Mouse movement injects force vectors into the fluid, creating organic wave trails. When idle, an autonomous demo driver animates the fluid automatically.
This component is designed as a full-bleed background container. Set its parent to
position: relative with an explicit width and height (e.g. 100vw / 100vh). The canvas fills its container automatically.Installation
Requires
three as a peer dependency.Usage
Props
string
default:"orange"
Primary fluid color. Accepts any valid CSS color string (
"#5227FF", "rgb(100,200,255)", named colors).string
default:"orange"
Secondary fluid color blended into the palette gradient.
string
default:"orange"
Tertiary fluid color for a richer multi-tone gradient effect.
number
default:"20"
Strength of force injected at the cursor position. Range
0–100; higher values create more dramatic wave displacement.number
default:"100"
Radius of the force injection area around the cursor in simulation units.
boolean
default:"false"
Enables viscous fluid behavior. When
true, a viscosity diffusion pass is applied each frame.number
default:"30"
Viscosity coefficient used when
isViscous is true. Higher values produce thicker, slower-moving fluid.number
default:"32"
Number of Jacobi iterations for the viscosity solver. More iterations increase accuracy at a performance cost.
number
default:"32"
Number of Jacobi iterations for the pressure (Poisson) solver.
number
default:"0.014"
Simulation time step per frame. Smaller values increase stability; larger values speed up the simulation.
boolean
default:"true"
Enables Back and Forth Error Compensation and Correction advection for improved numerical stability and detail.
number
default:"0.5"
Simulation resolution as a fraction of canvas size (
0.1–1.0). Higher values are sharper but more GPU-intensive.boolean
default:"false"
When
true, fluid velocity reflects off the boundary walls instead of dissipating.boolean
default:"true"
Enables the autonomous movement driver that animates the fluid when the user is idle.
number
default:"0.5"
Movement speed of the autonomous demo cursor in normalized units per second.
number
default:"2.2"
Force multiplier applied to the autonomous demo movement.
number
default:"0.25"
Duration in seconds for the smooth takeover transition when the user resumes control from auto-demo.
number
default:"3000"
Milliseconds of user inactivity before the autonomous demo driver resumes.
number
default:"0.6"
Duration in seconds for the auto-demo speed ramp-up on activation.
React.CSSProperties
Inline styles applied to the mount container
div.string
Additional CSS classes applied to the container.
Examples
Custom color palette
High-force interaction
Viscous fluid
Features
Real Fluid Simulation
Runs advection, divergence, pressure, and optional viscosity passes on the GPU every frame using Three.js WebGL.
Multi-Color Gradients
Three color stops are sampled from a dynamically generated palette texture for fluid color rendering.
Auto-Demo Mode
An autonomous cursor driver keeps the fluid animated when the user is idle, resuming gracefully on interaction.
Visibility Optimization
Uses
IntersectionObserver and document.visibilitychange to pause the render loop when off-screen or hidden.