🌊 Fluid Pointer Web Component

A beautiful, interactive fluid simulation web component built with WebGL and Lit. Create mesmerizing fluid effects that respond to mouse movement with zero dependencies.

Installation

npm install fluid-pointer

Quick Start

<!-- Basic usage -->
<fluid-pointer></fluid-pointer>

<!-- Customized -->
<fluid-pointer
	width="100%"
	height="400px"
	splat-force="2000"
	curl="15"
	colorful
	shading>
</fluid-pointer>

import "fluid-pointer"

// Or with module bundlers
import { FluidPointer } from "fluid-pointer"

Properties

Sizing

• width - Width (default: "100%")
• height - Height (default: "400px")
• aspect-ratio - Aspect ratio ("16:9", "1:1", etc.)
• responsive - Responsive behavior

Physics

• splat-force - Interaction force (default: 2000)
• curl - Swirl amount (default: 15)
• density-dissipation - Color fade rate: 0=no fade, higher=faster fade (default: 1.5)
• velocity-dissipation - Motion decay rate: 0=no decay, higher=faster decay (default: 1.2)

Visual

• colorful - Enable color transitions
• shading - Enable 3D shading effect
• color-mode - "rainbow" | "monochrome"
• color-transition-speed - Color change smoothness (default: 0.5)

Interaction

• mouse-interaction - Enable mouse interaction (default: true)
• interaction-mode - "movement" | "click" | "both"

Methods

const fluid = document.querySelector("fluid-pointer")

fluid.addSplat(0.5, 0.5, 100, -50, [1, 0, 0]) // x, y, velocityX, velocityY, color
fluid.addRandomSplats(5)
fluid.play()
fluid.pause()
fluid.reset()

Events

fluid.addEventListener("fluid-ready", (e) => {
	console.log("Simulation ready:", e.detail)
})

fluid.addEventListener("fluid-splat", (e) => {
	console.log("Splat created:", e.detail)
})

CSS Styling

fluid-pointer {
	--fluid-cursor: crosshair;
	border-radius: 12px;
	box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
}

/* Responsive square */
fluid-pointer.square {
	aspect-ratio: 1 / 1;
	width: 100%;
}

Examples

Card Background

<div class="card">
	<fluid-pointer style="position: absolute; inset: 0;"></fluid-pointer>
	<div class="content">Your content here</div>
</div>

Hero Section

<section class="hero">
	<fluid-pointer width="100vw" height="100vh" splat-force="1500" curl="20">
	</fluid-pointer>
</section>

Interactive Widget

<fluid-pointer
	width="300px"
	height="200px"
	color-mode="monochrome"
	splat-force="3000">
</fluid-pointer>

Dissipation Explained

The dissipation properties control how quickly the fluid effects fade:

• density-dissipation: Controls color/dye fading

  • 0.0 = Colors persist indefinitely
  • 1.5 = Slow fade (default)
  • 3.0 = Medium fade
  • 5.0 = Fast fade

• velocity-dissipation: Controls motion decay

  • 0.0 = Motion continues indefinitely
  • 1.2 = Slow decay (default)
  • 3.0 = Medium decay
  • 5.0 = Fast stop

Browser Support

• Chrome 51+
• Firefox 53+
• Safari 10+
• Edge 79+

Requires WebGL support.

License

MIT

Perfect for: Hero sections, interactive backgrounds, loading screens, creative portfolios, and any project needing engaging visual effects.