fluid-pointer-react/README.md

A dependency-free fluid simulation component with WebGL-based physics - supports both vanilla web components and React

# 🌊 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

```bash
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

```jsx
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

```jsx
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

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

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

```javascript
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

```javascript
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

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

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

## CSS Styling

```css
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

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

### Hero Section

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

### Interactive Widget

```html
<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.