R3F Canvas 3d

'use client'

import { DebugProvider } from '@/registry/lib/debug'
import { DebugCanvas } from '@/components/debug-canvas'

function Scene() {
  return (
    <>
      <ambientLight intensity={0.5} />
      <directionalLight position={[-5, 10, -5]} intensity={1} />

      <mesh position={[0, 0.5, 0]}>
        <boxGeometry />
        <meshStandardMaterial color="#6366f1" />
      </mesh>

      <mesh position={[2, 0.35, -1]}>
        <sphereGeometry args={[0.35, 32, 32]} />
        <meshStandardMaterial color="#ec4899" />
      </mesh>

      <mesh position={[-1.5, 0.25, 1]}>
        <cylinderGeometry args={[0.25, 0.25, 0.5, 32]} />
        <meshStandardMaterial color="#facc15" />
      </mesh>
    </>
  )
}

function DebugCanvasDemo() {
  return (
    <DebugProvider title="Canvas Debug" position="top-right" enabled>
      <div className="bg-background h-screen w-full">
        <DebugCanvas
          camera={{ position: [3, 3.5, 3.5], fov: 50 }}
          style={{ width: '100%', height: '100%' }}
        >
          <Scene />
        </DebugCanvas>
      </div>
    </DebugProvider>
  )
}

export default DebugCanvasDemo

Installation

pnpm dlx shadcn@latest add @joyco/debug-canvas

This will also install @joyco/debug if not already present.

Usage

Use DebugCanvas as a drop-in replacement for R3F's Canvas. It includes all debug helpers automatically:

import { DebugProvider } from '@/components/debug'
import { DebugCanvas } from '@/components/debug-canvas'
 
function App() {
  return (
    <DebugProvider>
      <DebugCanvas camera={{ position: [3, 2, 5], fov: 50 }}>
        {/* Your scene */}
      </DebugCanvas>
    </DebugProvider>
  )
}

All helpers are no-ops until the debug panel is opened (Alt+D or ?debug), then each can be individually toggled from the Canvas folder.

Debug Helpers

Orbit Controls

Enables @react-three/drei OrbitControls. Reads the camera target from camera.userData.target (if it's a Vector3) or projects 20 units along the camera's forward direction. Enables pointerEvents on the canvas while active.

Toggle: orbitControls in the Canvas folder.

Fly Controls

FPS-style camera controls — WASD movement, mouse look (pointer lock on click), Shift to sprint (5×), Space to ascend.

Toggle: flyControls in the Canvas folder, or Alt+F keyboard shortcut.

Note: Orbit and fly controls are mutually exclusive — enabling one automatically disables the other.

Grid Helper

Renders a <gridHelper args={[100, 100]} />.

Toggle: gridHelper in the Canvas folder.

Camera Monitor

Adds read-only cam pos and cam rot bindings to the Canvas folder. Updates every frame. Always visible when the Canvas folder exists — no toggle.

Perf Monitor

Mounts a stats-gl overlay (FPS, Hz) with custom TRI (triangles) and CALL (draw calls) panels. Positioned fixed at the bottom-right corner.

Toggle: perfMonitor in the Canvas folder.

Peer Dependencies

Your project must have @react-three/fiber and three installed.