npm package: @iamahmarfaraz/react-liquid-bg
Description: High-performance WebGL liquid fluid background for React
Author: Ahmar Faraz
Latest version: 1.0.3

<p align="center">
  <img src="./demo.gif" alt="react-liquid-bg demo" />
</p>

# @iamahmarfaraz/react-liquid-bg

A high-performance WebGL liquid fluid background component for React.

Built and maintained by **Ahmar Faraz**.

`@iamahmarfaraz/react-liquid-bg` provides a real-time, GPU-accelerated liquid simulation using WebGL and GLSL shaders.  
It is designed for production React applications where visuals, performance, and clean architecture matter.

This is **not** a CSS animation or video background.  
This is a real fluid simulation running entirely on the GPU.

---

## Features

- Real-time WebGL fluid simulation
- GPU-accelerated shader pipeline
- Interactive mouse-based fluid motion
- Full-screen responsive canvas
- Simple React component API
- Zero external animation libraries
- Production-grade architecture

---

## Installation

```bash
npm install @iamahmarfaraz/react-liquid-bg
```

or

```bash
yarn add @iamahmarfaraz/react-liquid-bg
```

---

## Basic Usage

```jsx
import LiquidBG from "@iamahmarfaraz/react-liquid-bg";

function App() {
  return (
    <div className="relative min-h-screen">
      <LiquidBG enabled={true} />
      <div className="relative z-10">
        Your App Content
      </div>
    </div>
  );
}

export default App;
```

---

## Conditional Usage

```jsx
<LiquidBG enabled={tab === null} />
```

The simulation starts when `enabled` is true and pauses when false.

---

## Props

| Prop | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | boolean | true | Starts or pauses the fluid simulation |
| className | string | "" | Custom class for the canvas |
| style | object | {} | Inline styles for the canvas |
| pointerEvents | boolean | true | Enable or disable pointer interaction |

---

## How It Works

The engine is a custom WebGL fluid solver using:

- Velocity advection
- Density advection
- Pressure solving
- Curl and vorticity forces
- Double framebuffer (ping-pong) rendering
- GLSL fragment shaders

All heavy computation is done on the GPU for maximum performance.

---

## Architecture Overview

### React Layer
- Exposes `<LiquidBG />`
- Controls lifecycle and canvas mount
- No re-renders during simulation

### Engine Layer
- WebGL context initialization
- Shader compilation and linking
- Framebuffer and texture management

### Simulation Layer
- Velocity field updates
- Pressure correction
- Vorticity and curl

### Rendering Layer
- Shader-based rendering
- Optional bloom and dithering
- Fullscreen adaptive scaling

---

## Interaction

- Mouse movement injects force
- Clicks generate splats
- Idle state keeps subtle motion
- Auto-resizes on window resize

---

## Performance

- Fully GPU-driven
- No React state updates per frame
- Optimized shaders and buffers
- Suitable for production apps

---

## Browser Support

- Chrome (recommended)
- Edge
- Firefox (WebGL enabled)
- Safari (WebGL enabled)

---

## License

MIT © Ahmar Faraz

This project is licensed under the MIT License.  
You are free to use, modify, and distribute this software in personal and commercial projects.

---

## Author

**Ahmar Faraz**  
Software Engineer  

GitHub: https://github.com/iamahmarfaraz  
LinkedIn: https://www.linkedin.com/in/iamahmarfaraz/

---

If you use this library in production, attribution is appreciated.