r3f-perf

Install r3f-perf as a development dependency using yarn.

yarn add --dev r3f-perf

To monitor the performance of your @react-three/fiber application with a visual interface, add the <Perf /> component anywhere inside your <Canvas /> component.

import { Canvas } from '@react-three/fiber'
import { Perf } from 'r3f-perf'

function App() {
  return (
    <Canvas>
      <Perf />
    </Canvas>
  )
}

If you want to access performance data without rendering the visual UI, use <PerfHeadless /> and the usePerf hook.

usePerf allows you to select specific parts of the performance state. You can also use getReport() for a non-reactive way to retrieve the current report.

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

const PerfHook = () => {
  // getPerf() is also available for non-reactive way
  const [gl, log, getReport] = usePerf((s) => s[(s.gl, s.log, s.getReport)])
  console.log(gl, log, getReport())
  return <PerfHeadless />
}

function App() {
  return (
    <Canvas>
      <PerfHook />
    </Canvas>
  )
}

You can inject custom metrics into the performance panel using setCustomData. It is recommended to throttle these updates (e.g., to once per second) to maintain readability.

Import setCustomData and call it within your frame loop or logic.

import { setCustomData, getCustomData } from 'r3f-perf'

const UpdateCustomData = () => {
  // recommended to throttle to 1sec for readability
  useFrame(() => {
    setCustomData(55 + Math.random() * 5) // will update the panel with the current information
  })
  return null
}

You can inject custom metrics into the Perf UI by passing a customData object to the Perf component. This will render a new entry in the performance bar with the provided name and info.

<Perf 
  customData={{ 
    name: 'My Metric', 
    info: '123' 
}} 
/>

The PerfProps interface defines the core performance monitoring configuration. Use these properties to control the frequency of logs, data analysis depth, and custom data visualization.

Key properties:

• logsPerSecond: Frequency of performance logging.
• overClock: Boolean to enable overclocking mode.
• matrixUpdate: Boolean to enable matrix updates.
• customData: An object of type customData containing specific numeric values for display.
• chart: An object of type chart defining the length and frequency (hz) of the performance chart.
• deepAnalyze: Boolean to enable deeper performance analysis.

// Example configuration object based on PerfProps
const perfConfig: PerfProps = {
  logsPerSecond: 60,
  overClock: true,
  customData: {
    name: 1,
    info: 2,
    value: 3,
    round: 4
  },
  chart: {
    length: 100,
    hz: 60
  }
};

The Perf component is the primary entry point for the r3f-perf library. It provides a visual overlay that monitors GPU/CPU usage, FPS, and other Three.js/R3F metrics. It can be configured to show a graph, run in a minimal mode, or perform deep analysis of programs and info.

import { Perf } from 'r3f-perf'

function App() {
  return (
    <Canvas>
      <Perf 
        showGraph={true} 
        deepAnalyze={true} 
        position="top-right"
      />
      {/* Your R3F components */}
    </Canvas>
  )
}

You can attach arbitrary metadata to the performance monitor using the custom data API. This is useful for labeling specific scenes, levels, or states in your application.

• setCustomData: Sets the custom data object.
• getCustomData: Retrieves the current custom data object.

import { setCustomData, getCustomData } from 'r3f-perf';

// Set custom metadata
setCustomData({ level: 'forest', difficulty: 'hard' });

// Retrieve it later
const data = getCustomData();

The r3f-perf store provides hooks and functions to interact with the performance monitoring state.

• usePerf: A React hook to access the performance state within a component.
• getPerf: A function to retrieve the current performance state outside of the React lifecycle.
• setPerf: A function to update the performance state manually.

import { usePerf, getPerf, setPerf } from 'r3f-perf';

// Inside a component
const perf = usePerf();

// Outside a component
const currentPerf = getPerf();

// Updating state
setPerf({ ... });