README.MD

r3f-webgpu-perf

Easily monitor the performance of your @react-three/fiber application — built for React Three Fiber 8+ and designed to work with both WebGPU and WebGL renderers (including WebGPU setups where gl.info may be unavailable).

Inspired by r3f-perf.

Add <Perf /> inside your Canvas	Live demo

Features

• WebGPU & WebGL — drop <Perf /> into any R3F Canvas; stats are collected from gl.info on WebGL or via scene traversal on WebGPU.
• Light & dark mode — toggle the theme with the sun/moon button so the panel stays readable over bright or dark scenes.
• Compact or expanded — click the chevron to expand the panel and reveal scene breakdown: draw calls, triangles, geometries, textures, lines, and points.
• Minimize to a dot — hide the full panel with the eye button; it collapses to a small dot in the corner so it does not obstruct the viewport. Click the dot to bring it back.
• FPS gauge, live graph & VRAM — circular gauge (cycles FPS → GPU → CPU), real-time graph, and optional VRAM estimate bar.

Installation

npm i r3f-webgpu-perf

Peer dependencies (already present in most R3F projects):

• react >= 18
• react-dom >= 18
• @react-three/fiber >= 8
• three >= 0.150

Usage

Add <Perf /> anywhere inside your <Canvas>:

import { Canvas } from "@react-three/fiber";
import { Perf } from "r3f-webgpu-perf";

function App() {
  return (
    <Canvas>
      <Perf position="top-left" />
      {/* your scene */}
    </Canvas>
  );
}

Options

Prop	Default	Description
position	'top-left'	Panel position: top-left, top-right, bottom-left, bottom-right
showGraph	true	Show real-time FPS/GPU/CPU graph
showGauge	true	Show circular gauge (click to cycle FPS → GPU → CPU)
minimal	false	Condensed view with essential metrics only
showVRAM	false	Show estimated VRAM usage bar
logsPerSecond	10	How often scene stats refresh
openByDefault	true	Show panel on load (set false to start minimized as a dot in the corner)
className	—	Custom CSS class on the portal wrapper
style	—	Inline styles on the portal wrapper

Advanced: headless mode

Use PerfHeadless to collect metrics without the built-in UI, and read values with usePerf:

import { Canvas } from "@react-three/fiber";
import { PerfHeadless, usePerf } from "r3f-webgpu-perf";

function PerfLogger() {
  const fps = usePerf((s) => s.fps);
  console.log("FPS:", fps);
  return <PerfHeadless logsPerSecond={10} />;
}

function App() {
  return (
    <Canvas>
      <PerfLogger />
    </Canvas>
  );
}

You can also build a custom UI with PerfPanel and wire it yourself outside the canvas if needed.

API exports

import {
  Perf,
  PerfHeadless,
  PerfPanel,
  usePerf,
  perfActions,
  getPerf,
  perfState,
} from "r3f-webgpu-perf";

WebGPU vs WebGL

Metric	Source
FPS / frame time	Measured via performance.now()
GPU / CPU ms	Estimated (20% / 80% split of frame delta)
Draw calls, triangles, geometries, textures	gl.info when available (WebGL), otherwise manual scene traversal (WebGPU fallback)
VRAM	Estimated from geometry attributes and texture sizes

Real WebGPU timestamp queries are not implemented yet — planned for a future release.

Development

git clone https://github.com/ektogamat/r3f-webgpu-perf.git
cd r3f-webgpu-perf
npm install
npm run dev         # WebGPU demo with hot reload (Chrome/Edge recommended)
npm run build       # build library to dist/
npm run build:demo  # build demo to demo-dist/

The demo uses WebGPU + TSL post-processing (RenderPipeline, bloom, chromaticAberration).

Changelog

See CHANGELOG.md.

License

MIT © Anderson Mancini