@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

npm install @iamahmarfaraz/react-liquid-bg

or

yarn add @iamahmarfaraz/react-liquid-bg

Basic Usage

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

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