ThreeCanvas component for React

Want to use vanilla Three.js in React without the hassle? This component does the heavy lifting for you: no frameworks, no fuss.

Whether you're embedding an existing project or just want to avoid extra frameworks, adding Three.js to React can be a pain. This component gives you a ready-to-go canvas, renderer, camera, scene, and EffectComposer (WebGL only), with WebXR support built in.

By default, you get a WebGLRenderer, but you can switch to WebGPURenderer just by importing from @mesmotronic/react-three-canvas/webgpu instead of @mesmotronic/react-three-canvas.

Installation

Install the package (and peer dependencies if you don't already have them):

npm install @mesmotronic/react-three-canvas

# If you don't already have them:
npm install three react react-dom

Usage

The ThreeCanvas component gives you a canvas with a Three.js renderer attached, plus callbacks for animation, mounting, unmounting, and resizing, and an EffectComposer for postprocessing (WebGL only).

Example: Class component

Class components are a great fit for integrating Three.js, so ThreeCanvasComponent gives you an extendible class with a ThreeCanvas that fills its parent. You can override any of the lifecycle methods below (they're all optional):

import * as THREE from 'three';
import { ThreeCanvasComponent } from '@mesmotronic/react-three-canvas';

class App extends ThreeCanvasComponent {
  public override canvasDidMount = ({ scene }) => {
    const geometry = new THREE.BoxGeometry(1, 1, 1);
    const material = new THREE.MeshBasicMaterial({ color: 0xff0000 });
    const mesh = new THREE.Mesh(geometry, material);
    scene.add(mesh);
    this.cube = mesh;
  };

  public override canvasWillAnimate = () => {
    const { cube } = this;
    cube.rotation.x += 0.01;
    cube.rotation.y += 0.01;
  };

  public override canvasDidResize = () => {
    console.log('Resized');
  };

  public override canvasWillUnmount = () => {
    console.log('Unmounting');
  };
};

export default App;

Example: Functional component

Prefer functional components? ThreeCanvas works great there too! Just be sure to manage your props and hooks so you keep a single canvas instance.

Tip: Use useRef or useCallback if you need to persist data between renders.

import * as THREE from "three";
import { ThreeCanvas } from "@mesmotronic/react-three-canvas";

const App = () => {
  const mountHandler = useCallback(({ scene, camera, userData }) => {
    const geometry = new THREE.BoxGeometry();
    const material = new THREE.MeshBasicMaterial({ color: 0xff0000 });
    const cube = new THREE.Mesh(geometry, material);
    scene.add(cube);
    camera.position.z = 5;
    userData.cube = cube;
  }, []);

  const animationFrameHandler = useCallback(({ userData }) => {
    const { cube } = userData;
    cube.rotation.x += 0.01;
    cube.rotation.y += 0.01;
  }, []);

  const resizeHandler = useCallback(() => console.log("Resized"), []);
  const unmountHandler = useCallback(() => console.log("Unmounting"), []);

  return (
    <ThreeCanvas
      style={{ width: "100%", height: "100%" }}
      onMount={mountHandler}
      onAnimationFrame={animationFrameHandler}
      onResize={resizeHandler}
      onUnmount={unmountHandler}
    />
  );
};

export default App;

Props and lifecycle methods

| Prop | Lifecycle method | Type | Description | | ------------------ | ------------------- | ---------- | ---------------------------------- | | onMount | canvasDidMount | function | Called when the component mounts | | onAnimationFrame | canvasWillAnimate | function | Called on each animation frame | | onResize | canvasDidResize | function | Called when the canvas resizes | | onUnmount | canvasWillUnmount | function | Called when the component unmounts |

All other props (like style, className, etc.) are passed directly to the <canvas> element.

Callback props

All callback props (onMount, onAnimationFrame, onResize, onUnmount) and their equivalent lifecycle methods receive a single argument of type ThreeCanvasCallbackProps:

| Property | Type | Description | | ---------- | ----------------------------------------- | -------------------------------------------------- | | canvas | HTMLCanvasElement | The canvas element being rendered to | | renderer | THREE.WebGLRenderer or WebGPURenderer | The Three.js renderer instance | | camera | THREE.PerspectiveCamera | The camera used for rendering | | composer | EffectComposer | The EffectComposer for postprocessing (WebGL only) | | scene | THREE.Scene | The Three.js scene | | size | THREE.Vector2 | The current size of the canvas | | clock | THREE.Clock | An instance of THREE.Clock for animation timing | | userData | Record<string, any> | A persistent object for your own data |

TypeScript:

type ThreeCanvasCallbackProps = {
  canvas: HTMLCanvasElement;
  renderer: THREE.WebGLRenderer;
  camera: THREE.PerspectiveCamera;
  composer: EffectComposer;
  scene: THREE.Scene;
  size: THREE.Vector2;
  userData: Record<string, any>;
};

Features

• Automatic canvas resizing with ResizeObserver
• Integrated EffectComposer for post-processing effects (WebGL only)
• WebXR support via renderer.xr.enabled
• Clean resource disposal on unmount

Peer Dependencies

• three: Three.js library for 3D rendering
• react: React for component rendering

License

BSD 2-Clause License