React Fluid Fire 🔥

A physics-based fire simulation library for React/Next.js using Navier-Stokes fluid dynamics equations. Create realistic fire effects with customizable colors, shapes, and physics.

Features

✅ Full Physics Simulation - Based on Navier-Stokes equations
✅ Multiple Fire Colors - Fire, Blue, Toxic, Purple, Ice, Lava, Rainbow, Smoke
✅ Flexible Floor Shapes - Bottom, Top, Left, Right, Circle, Box, Diagonal, Wave
✅ Interactive - Click/drag to create heat and obstacles
✅ SVG Rendering - No Canvas, pure SVG + JavaScript
✅ React Hooks - Easy integration with useFluidFire hook
✅ TypeScript Ready - Full type support (coming soon)
✅ Next.js Compatible - Works with SSR/SSG

Installation

npm install react-fluid-fire
# or
yarn add react-fluid-fire
# or
pnpm add react-fluid-fire

Quick Start

Basic Usage

import { FluidFire } from 'react-fluid-fire';

function App() {
  return (
    <FluidFire
      width={800}
      height={600}
      colorScheme="fire"
      floorShape="bottom"
    />
  );
}

With Custom Configuration

import { FluidFire } from 'react-fluid-fire';

function App() {
  return (
    <FluidFire
      width={800}
      height={600}
      fps={30}
      gridResolution={10000}
      
      // Physics
      gravity={0.0}
      numIters={10}
      
      // Fire sources
      burningFloor={true}
      burningObstacle={false}
      
      // Floor shape
      floorShape="wave"
      floorThickness={4}
      floorCurve={50}
      
      // Visual effects
      colorScheme="blue"
      showSwirls={true}
      swirlProbability={50}
      
      // Styling
      backgroundColor="#000000"
      interactive={true}
      
      // Callbacks
      onSimulationReady={(sim) => console.log('Ready!', sim)}
      onMouseMove={({ x, y }) => console.log(x, y)}
    />
  );
}

Using the Hook (Advanced)

import { useRef } from 'react';
import { useFluidFire } from 'react-fluid-fire';

function CustomFireComponent() {
  const svgRef = useRef(null);
  
  const { isReady, isPaused, stats, togglePause, reset } = useFluidFire({
    svgRef,
    width: 800,
    height: 600,
    colorScheme: 'purple',
    floorShape: 'circle',
  });

  return (
    <div>
      <svg ref={svgRef} viewBox="0 0 800 600">
        <rect width="800" height="600" fill="#000" />
        <g id="fluidGrid" />
        <g id="obstacleGroup" />
      </svg>
      
      {isReady && (
        <div>
          <p>FPS: {stats.fps} | Frame: {stats.frame} | Swirls: {stats.swirls}</p>
          <button onClick={togglePause}>
            {isPaused ? 'Play' : 'Pause'}
          </button>
          <button onClick={reset}>Reset</button>
        </div>
      )}
    </div>
  );
}

Props

FluidFire Component Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | width | number | 800 | SVG width in pixels | | height | number | 600 | SVG height in pixels | | fps | number | 30 | Target frames per second | | gridResolution | number | 10000 | Number of simulation cells | | gravity | number | 0.0 | Gravity force (-5 to 5) | | numIters | number | 10 | Pressure solver iterations | | burningFloor | boolean | true | Enable floor as fire source | | burningObstacle | boolean | false | Enable obstacle as fire source | | floorShape | string | 'bottom' | Floor shape (see below) | | floorThickness | number | 4 | Floor thickness in cells | | floorCurve | number | 0 | Floor curve amount (0-100) | | colorScheme | string | 'fire' | Color scheme (see below) | | showSwirls | boolean | false | Show swirl particles | | swirlProbability | number | 50 | Swirl spawn probability | | interactive | boolean | true | Enable mouse/touch interaction | | backgroundColor | string | '#000000' | Background color | | onSimulationReady | function | null | Callback when ready | | onMouseMove | function | null | Callback on mouse move |

Floor Shapes

• bottom - Horizontal floor at bottom
• top - Horizontal floor at top
• left - Vertical floor on left
• right - Vertical floor on right
• circle - Circular ring in center
• box - All four sides
• diagonal - Diagonal line
• wave - Sine wave pattern

Color Schemes

• fire - Classic orange/yellow fire 🔥
• blue - Blue fire (hotter) 💙
• toxic - Green toxic fire ☢️
• purple - Purple magic fire 🔮
• ice - Cyan ice fire ❄️
• lava - Hot metal/lava 🌋
• rainbow - Rainbow spectrum 🌈
• smoke - Grayscale smoke 💨
• custom - Custom color function

Custom Color Scheme

import { setCustomColorScheme } from 'react-fluid-fire';

// Define custom color function
setCustomColorScheme((temp) => {
  // temp is 0.0 to 1.0
  const r = Math.floor(255 * temp);
  const g = Math.floor(128 * (1 - temp));
  const b = 100;
  return [r, g, b];
});

// Use it
<FluidFire colorScheme="custom" />

Examples

Fire from Bottom

<FluidFire
  floorShape="bottom"
  colorScheme="fire"
  burningFloor={true}
/>

Fire Falling from Top

<FluidFire
  floorShape="top"
  colorScheme="blue"
  gravity={-2}
  burningFloor={true}
/>

Circular Fire Ring

<FluidFire
  floorShape="circle"
  floorCurve={80}
  colorScheme="purple"
  burningFloor={true}
/>

Wave Pattern Fire

<FluidFire
  floorShape="wave"
  floorCurve={60}
  colorScheme="lava"
  burningFloor={true}
/>

Toxic Smoke from Sides

<FluidFire
  floorShape="box"
  colorScheme="toxic"
  burningFloor={true}
  showSwirls={true}
/>

Physics Behind the Simulation

This library implements the Navier-Stokes equations for fluid dynamics:

• Advection - Semi-Lagrangian method for velocity transport
• Incompressibility - Gauss-Seidel solver with SOR (Successive Over-Relaxation)
• Buoyancy - Hot gas rises (Archimedes principle)
• Swirls - Vortex particles with angular velocity
• MAC Grid - Staggered grid for accurate pressure computation

For detailed physics explanation, see the PDF documentation.

Next.js Usage

Works perfectly with Next.js App Router or Pages Router:

'use client'; // App Router

import { FluidFire } from 'react-fluid-fire';

export default function Page() {
  return (
    <div className="w-full h-screen">
      <FluidFire
        width={800}
        height={600}
        colorScheme="fire"
      />
    </div>
  );
}

Performance Tips

• Lower gridResolution for better performance (try 5000-8000)
• Reduce fps to 20-25 for complex scenes
• Disable showSwirls if not needed
• Use simpler floorShape (bottom/top vs wave)

Browser Support

• ✅ Chrome/Edge 90+
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Mobile browsers (iOS Safari, Chrome Mobile)

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

Credits

Based on the Navier-Stokes fluid dynamics simulation technique.