🌊 Fluid Pointer Component Library

A beautiful, interactive fluid simulation component library with WebGL-based physics. Create mesmerizing fluid effects that respond to mouse movement with zero external dependencies. Available as both a vanilla web component and a React component.

Installation

npm install fluid-pointer-react

React Component (Recommended)

Important: Make sure to import both the component and the CSS file for proper styling.

Quick Start

import { FluidPointer } from "fluid-pointer-react/react"
import "fluid-pointer-react/css"

function App() {
	return (
		<FluidPointer
			width="100%"
			height="400px"
			splatForce={2000}
			curl={15}
			colorMode="rainbow"
			shading
		/>
	)
}

With Ref and Event Handlers

import { FluidPointer } from "fluid-pointer-react/react"
import "fluid-pointer-react/css"
import { useRef } from "react"

function InteractiveFluid() {
	const fluidRef = useRef(null)

	const addRandomSplat = () => {
		fluidRef.current?.addSplat(
			Math.random(),
			Math.random(),
			(Math.random() - 0.5) * 1000,
			(Math.random() - 0.5) * 1000
		)
	}

	return (
		<div>
			<FluidPointer
				ref={fluidRef}
				width="100%"
				height="300px"
				onFluidReady={(e) => console.log("Simulation ready!", e)}
				onFluidSplat={(e) => console.log("Splat created!", e)}
			/>
			<button onClick={addRandomSplat}>Add Random Splat</button>
			<button onClick={() => fluidRef.current?.pause()}>Pause</button>
			<button onClick={() => fluidRef.current?.play()}>Play</button>
			<button onClick={() => fluidRef.current?.reset()}>Reset</button>
		</div>
	)
}

Vanilla Web Component

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.