API Reference

DebugViews

R3F component for presenting debug views inside a React Three Fiber <Canvas>. Import it from threejs-debug-view/r3f.

The root package export stays React-free. Use it for core helpers, built-in view definitions, render planning, and public types.

type DebugViewsMode = "compose" | "viewport"

Important props:

| Prop | Purpose | | --- | --- | | views | Registered debug views. | | mode | compose or viewport. Defaults to compose. | | activeView | Selected view for single/overlay flows. | | layout | Layout preset or layout config. | | viewportViews | Explicit viewport assignments for viewport mode. | | showLabels | Renders DOM labels over panes. | | viewportLabels | Label overrides or formatter. | | overlayOpacity | Blend amount for overlay mode. |

DebugView

interface DebugView {
  id?: string
  label: string
  node?: DebugNode
  mode?: "passthrough" | "normal" | "depth" | "heatmap"
  source?: DebugViewSource
  scale?: number
  bias?: number
}

DebugViewportView

interface DebugViewportView {
  view: number | DebugViewSource | DebugView
  label?: string
  camera?: Camera
  resolutionScale?: number
}

resolutionScale is normalized to 1, 0.5, or 0.25.

Built-in DebugViewSource values include shaderCost, which uses mode: "heatmap" and reports estimated shader complexity. It is not a native GPU instruction counter.

Package Shape

The package has two public entrypoints:

| Entrypoint | Use it for | | --- | --- | | threejs-debug-view | Core helpers, built-in views, TSL compositor helpers, planning utilities, and public types. | | threejs-debug-view/r3f | The React Three Fiber overlay plus useDebugViewsControls() for Leva. |

The repository demo and docs are separate from the package source:

• components/debug-views/ contains package source.
• src/ contains the Vite demo app.
• packages/docs/ contains the Astro documentation site.

Helpers

• createCustomDebugView()
• createDebugViewportPlan()
• createDebugViewportRenderGraphPlan()
• createDebugViewportLabels()
• createDebugViewportRects()
• useDebugViewsControls() from threejs-debug-view/r3f