react-webgl-fluid-canvas

Reusable React package for webgl-fluid with:

• full access to the original simulation options
• named presets for fast setup
• client-safe lazy loading
• device-aware mobile presets
• animated surface color support
• optional provider pattern for shared surface-color transitions
• hover, press, and tracked touch relay helpers for iOS and Android

Install

npm install react-webgl-fluid-canvas

Peer dependencies:

• react
• react-dom

The package installs webgl-fluid for you.

Documentation map

• API reference
• Next.js guide
• Troubleshooting
• Publishing guide
• Example files

Basic usage

"use client";

import { FluidCanvas } from "react-webgl-fluid-canvas";

export function HeroBackground() {
  return (
    <div style={{ position: "fixed", inset: 0 }}>
      <FluidCanvas
        preset="hero"
        style={{ width: "100%", height: "100%" }}
      />
    </div>
  );
}

Full simulation control

Every original webgl-fluid option is available through options.

"use client";

import { FluidCanvas, createFluidOptions } from "react-webgl-fluid-canvas";

export function CinematicFluid() {
  return (
    <FluidCanvas
      style={{ width: "100vw", height: "100vh" }}
      surfaceColor={{ r: 12, g: 14, b: 18 }}
      surfaceColorTransitionMs={700}
      options={createFluidOptions({
        BLOOM: true,
        BLOOM_INTENSITY: 0.45,
        BLOOM_THRESHOLD: 0.55,
        SUNRAYS: true,
        SUNRAYS_WEIGHT: 0.75,
        SHADING: true,
        COLORFUL: true,
        SPLAT_FORCE: 3200,
        SPLAT_RADIUS: 0.2,
      })}
    />
  );
}

FluidCanvas now keeps BACK_COLOR aligned with surfaceColor by default. If you need a different simulation background, pass syncBackgroundColorToSurface={false} or set options.BACK_COLOR explicitly.

Easy mobile touch and hover relay

Use useFluidInputBindings when another element should drive the fluid canvas. This is the package version of the touch and hover relay logic you added in the original app.

"use client";

import {
  FluidCanvas,
  useFluidInputBindings,
} from "react-webgl-fluid-canvas";

export function Landing() {
  const fluidInput = useFluidInputBindings<HTMLButtonElement>({
    relayHover: true,
    relayTouch: true,
    useWindowTouchTracking: true,
    suppressClickOnTouchDrag: true,
  });

  return (
    <>
      <FluidCanvas style={{ position: "fixed", inset: 0 }} />
      <button
        {...fluidInput.bind}
        onClick={(event) => {
          if (fluidInput.shouldSuppressClick) {
            event.preventDefault();
            return;
          }

          console.log("real click");
        }}
        style={{ position: "relative", zIndex: 1 }}
      >
        Open
      </button>
    </>
  );
}

Presets

Use a preset when you want a strong starting point without manually tuning the whole simulation:

<FluidCanvas preset="glass" />

Available presets:

• default
• hero
• glass
• ink
• aurora

You can still override any option on top of a preset:

<FluidCanvas
  preset="aurora"
  options={{
    BLOOM_INTENSITY: 0.22,
    SUNRAYS_WEIGHT: 0.5,
  }}
/>

If you only want specific elements to drive the fluid and you do not want global page-wide splats, disable global listeners on the canvas:

<FluidCanvas
  enableGlobalPointerEvents={false}
  style={{ position: "fixed", inset: 0 }}
/>

Shared surface color transitions

Use the provider helpers when one fullscreen canvas should stay mounted while routes or sections change the visible base color:

"use client";

import {
  FluidSurfaceCanvas,
  FluidSurfaceProvider,
  useFluidSurface,
} from "react-webgl-fluid-canvas";

function RouteColorSync() {
  const { resetSurfaceColor, setSurfacePreset } = useFluidSurface();

  return (
    <>
      <button onClick={() => setSurfacePreset("glass")}>Glass</button>
      <button onClick={() => resetSurfaceColor()}>Reset</button>
    </>
  );
}

export function AppShell() {
  return (
    <FluidSurfaceProvider initialPreset="hero">
      <FluidSurfaceCanvas
        preset="hero"
        style={{ position: "fixed", inset: 0 }}
        surfaceColorTransitionMs={700}
      />
      <RouteColorSync />
    </FluidSurfaceProvider>
  );
}

Imperative control

Use a ref when you want direct canvas control from app code without depending on global listeners or window-level relays:

"use client";

import { useRef } from "react";
import {
  FluidCanvas,
  type FluidCanvasHandle,
} from "react-webgl-fluid-canvas";

export function ControlledFluid() {
  const fluidRef = useRef<FluidCanvasHandle>(null);

  return (
    <>
      <FluidCanvas
        ref={fluidRef}
        preset="ink"
        enableGlobalPointerEvents={false}
        style={{ position: "fixed", inset: 0 }}
      />
      <button
        onClick={() => fluidRef.current?.relayPress(window.innerWidth / 2, 200)}
      >
        Trigger splash
      </button>
    </>
  );
}

Device presets and helpers

createFluidOptions

Merges:

1. DEFAULT_FLUID_OPTIONS
2. device-safe overrides
3. your overrides

import { createFluidOptions } from "react-webgl-fluid-canvas";

const options = createFluidOptions({
  BLOOM: true,
  SUNRAYS: true,
});

createFluidPresetOptions

Builds options from a preset, then applies device-safe overrides, then your final overrides.

import { createFluidPresetOptions } from "react-webgl-fluid-canvas";

const options = createFluidPresetOptions("hero", {
  SPLAT_FORCE: 3200,
});

detectFluidDeviceProfile

Returns one of:

• "desktop"
• "android"
• "ios"
• "touch"
• "unknown"

getDeviceFluidOptions

Returns only the device-specific safety overrides.

warmupFluidCanvas

Preloads the webgl-fluid chunk early.

"use client";

import { useEffect } from "react";
import { warmupFluidCanvas } from "react-webgl-fluid-canvas";

export function FluidWarmup() {
  useEffect(() => {
    void warmupFluidCanvas();
  }, []);

  return null;
}

Direct relay functions

If you do not want the hook, you can relay events manually.

import {
  relayFluidHover,
  relayFluidPress,
  relayFluidRelease,
} from "react-webgl-fluid-canvas";

relayFluidHover(x, y);
relayFluidPress(x, y);
relayFluidRelease(x, y);

FluidCanvas props

• className?: string
• style?: React.CSSProperties
• preset?: FluidPresetName
• options?: FluidOptions
• interactive?: boolean
• enableGlobalPointerEvents?: boolean
• enableExternalInputRelay?: boolean
• enableDeviceOptimizations?: boolean
• deviceProfile?: "auto" | FluidDeviceProfile
• surfaceColor?: FluidColor
• surfaceColorTransitionMs?: number
• syncBackgroundColorToSurface?: boolean

useFluidInputBindings options

• enabled?: boolean
• dragThreshold?: number
• relayHover?: boolean
• relayPointerMove?: boolean
• relayPointerDown?: boolean
• relayPointerUp?: boolean
• relayTouch?: boolean
• useWindowTouchTracking?: boolean
• suppressClickOnTouchDrag?: boolean

Exported values

Components and hooks:

• FluidCanvas
• FluidCanvasHandle
• FluidSurfaceCanvas
• FluidSurfaceProvider
• useFluidInputBindings
• useFluidSurface
• UseFluidSurfaceResult

Config helpers:

• DEFAULT_FLUID_OPTIONS
• IOS_SAFE_FLUID_OPTIONS
• ANDROID_SAFE_FLUID_OPTIONS
• FLUID_PRESETS
• DEFAULT_SURFACE_COLOR
• createFluidOptions
• createFluidPresetOptions
• detectFluidDeviceProfile
• getFluidPreset
• getFluidPresetSurfaceColor
• getDeviceFluidOptions
• resolveFluidCanvasOptions
• warmupFluidCanvas

Relay helpers:

• dispatchFluidInputRelay
• relayFluidPointer
• relayFluidHover
• relayFluidPress
• relayFluidRelease

Types:

• FluidColor
• FluidCanvasRelayInput
• FluidOptions
• FluidInputRelayDetail
• FluidInputBindingsOptions
• FluidDeviceProfile
• FluidPresetDefinition
• FluidPresetName

Notes

• Use the package from a client component in Next.js.
• surfaceColor controls the visible base color under the transparent fluid layer.
• surfaceColor also becomes the simulation BACK_COLOR by default unless you opt out or override options.BACK_COLOR.
• iOS and Android can be tuned automatically, or you can disable that with enableDeviceOptimizations={false}.
• interactive now controls the default global-window interaction behavior. External relayed input remains enabled by default unless enableExternalInputRelay={false} is passed.
• Before publishing to npm, update the package name and repository metadata in package.json.