These demos are real, you can click them! They contain the full code, too.

npm install react-three-fiber

React-three-fiber is a small React renderer for Three-js. Why, you might ask? React was made to drive complex tree structures, it makes just as much sense for Three as it makes for the Dom. Building a dynamic scene graph becomes so much easier because you can break it up into declarative, re-usable components with clean, reactive semantics. This also opens up the eco system, you can now apply generic packages for state, animation, gestures and so on.

Difference to react-three, react-three-renderer, react-three-renderer-fiber

This is a small reconciler config with a few additions for interaction and hooks holding it all together. It does not know or care about Three internals, it uses heuristics for objects and attributes, so that we can get away without creating a strong dependency. Three is constantly changing, we don't want to rely on a specific version or chase their release cycle. This library works with version 1 as well as their latest. At the same time we don't want to alter any rules, if something works in Three in a specific way, it will be the same here.

How it looks like ...

Copy the following into a project to get going. Here's the same running in a code sandbox.

import * as THREE from 'three'
import React from 'react'
import ReactDOM from 'react-dom'
import { Canvas } from 'react-three-fiber'

function Thing({ vertices, color }) {
  return (
    <group ref={ref => console.log('we have access to the instance')}>
      <line>
        <geometry
          attach="geometry"
          vertices={vertices.map(v => new THREE.Vector3(...v))}
          onUpdate={self => (self.verticesNeedUpdate = true)}
        />
        <lineBasicMaterial attach="material" color="black" />
      </line>
      <mesh 
        onClick={e => console.log('click')} 
        onHover={e => console.log('hover')} 
        onUnhover={e => console.log('unhover')}>
        <octahedronGeometry attach="geometry" />
        <meshBasicMaterial attach="material" color="peachpuff" opacity={0.5} transparent />
      </mesh>
    </group>
  )
}

ReactDOM.render(
  <Canvas>
    <Thing vertices={[[-1, 0, 0], [0, 1, 0], [1, 0, 0], [0, -1, 0], [-1, 0, 0]]} />
  </Canvas>,
  document.getElementById('root')
)

Objects and properties

You can use Three's entire object catalogue and all properties. When in doubt, always consult the docs.

<mesh
  visible
  userData={{ test: "hello" }}
  position={new THREE.Vector3(1, 2, 3)}
  rotation={new THREE.Euler(0, 0, 0)}
  geometry={new THREE.SphereGeometry(1, 16, 16)}
  material={new THREE.MeshBasicMaterial({ color: new THREE.Color('indianred'), transparent: true })} />

Shortcuts and non-Object3D stow-away

All properties that have a .set() method (colors, vectors, euler, matrix, etc) can be given a shortcut. For example THREE.Color.set can take a color string, hence instead of color={new THREE.Color('peachpuff') you can do color="peachpuff". Some set-methods take multiple arguments (vectors for instance), in this case you can pass an array.

You can stow away non-Object3D primitives (geometries, materials, etc) into the render tree so that they become managed and reactive. They take the same properties they normally would, constructor arguments are passed with args. Using the attach property they bind automatically to their parent.

The following is the same as above, but it's leaner and critical properties aren't re-instanciated on every render.

<mesh visible userData={{ test: "hello" }} position={[1, 2, 3]} rotation={[0, 0, 0]}>
  <sphereGeometry attach="geometry" args={[1, 16, 16]} />
  <meshStandardMaterial attach="material" color="indianred" transparent />
</mesh>

You can nest primitive objects, good for awaiting async textures and such. You could use React-suspense if you wanted!

<meshBasicMaterial attach="material">
  <texture attach="map" format={THREE.RGBFormat} image={img} onUpdate={self => img && (self.needsUpdate = true)} />
</meshBasicMaterial>

Sometimes attaching isn't enough, for instance effects cling to an array called "passes" of a the parental effect-component. In that case you use attachArray which adds the object to the target array and takes it out on unmount:

<effectComposer>
  <renderPass attachArray="passes" />
  <glitchPass attachArray="passes" renderToScreen />
</effectComposer>

You can also attach to existing objects using attachObject, which adds the object onto a property on the parent, and takes it out on unmount.

<bufferGeometry>
  <bufferAttribute
    attachObject={['attributes', 'position']}
    array={vertices} 
    itemSize={3} />
</bufferGeometry>

Piercing into nested properties

If you want to reach into nested attributes (for instance: mesh.rotation.x), just use dash-case:

<mesh rotation-x={1} material-color="lightblue" geometry-vertices={newVertices} />

Extending or using arbitrary objects

When you need managed local (or custom/extended) objects, you can use the primitive placeholder.

const mesh = new THREE.Mesh()
return <primitive object={mesh} />

Events

THREE objects that implement their own raycast method (for instance meshes, lines, etc) can be interacted with by declaring events on the object. For now that's prop-updates (very useful for things like verticesNeedUpdate), hovering-state and clicks. Touch follows soon!

<mesh
  onClick={e => console.log('click')}
  onHover={e => console.log('hover')}
  onUnhover={e => console.log('unhover')}
  onUpdate={self => console.log('props have been updated')}
/>

Gl data & hooking into the render loop

Sometimes you're running effects, postprocessing, etc that needs to get updated. You can fetch the renderer, the camera, scene, and a render-loop subscribe to do this. You can only use these hooks inside the Canvas render tree (they're context based)!

import { Canvas, useRender, useThree } from 'react-three-fiber'

function App() {
  // gl is the webgl-renderer
  // canvas the dom element that was created
  // size the bounds of the view (which stretches 100% and auto-adjusts)
  // viewport is the calculated screen-size, it's a function
  const { gl, canvas, scene, camera, size, viewport } = useThree()
  // Subscribes to the render-loop, gets cleaned up automatically when the component unmounts
  // Add a "true" as the 2nd argument and you take over the render-loop
  useRender(({ gl, canvas, scene, camera }) => console.log("i'm in the render-loop"))
  return <group />
}

Receipes

Handling loaders

You can use Reacts built-in memoizing-features (as well as suspense) to build async dependence graphs.

function Image({ url }) {
  const texture = useMemo(() => new THREE.TextureLoader().load(url), [url])
  return (
    <mesh>
      <planeBufferGeometry attach="geometry" args={[1, 1]} />
      <meshLambertMaterial attach="material" transparent>
        <primitive attach="map" object={texture} />
      </meshLambertMaterial>
    </mesh>
  )
}

Dealing with effects (hijacking main render-loop)

Managing effects can get quite complex normally. Drop the component below into a scene and you have a live effect. Remove it and everything is as it was without any re-configuration.

import { apply, Canvas, useRender, useThree } from 'react-three-fiber'
import { EffectComposer } from './postprocessing/EffectComposer'
import { RenderPass } from './postprocessing/RenderPass'
import { GlitchPass } from './postprocessing/GlitchPass'
// Makes these objects available as native objects "<renderPass />" and so on
apply({ EffectComposer, RenderPass, GlitchPass })

function Effects({ factor }) {
  const { gl, scene, camera, size } = useThree()
  const composer = useRef()
  useEffect(() => void composer.current.obj.setSize(size.width, size.height), [size])
  // This takes over as the main render-loop (when 2nd arg is set to true)
  useRender(() => composer.current.obj.render(), true)
  return (
    <effectComposer ref={composer} args={[gl]}>
      <renderPass attachArray="passes" args={[scene, camera]} />
      <glitchPass attachArray="passes" factor={factor} renderToScreen />
    </effectComposer>
  )
}

Heads-up display (rendering multiple scenes)

useRender allows components to hook into the render-loop, or even to take it over entirely. That makes it possible for one component to render over the content of another. The order of these operations is established by the scene-graph.

function Content({ camera }) {
  const scene = useRef()
  useRender(({ gl }) => void ((gl.autoClear = true), gl.render(scene.current, camera)), true)
  return <scene ref={scene}>{/* ... */}</scene>
}

function HeadsUpDisplay({ camera }) {
  const scene = useRef()
  useRender(({ gl }) => void ((gl.autoClear = false), gl.clearDepth(), gl.render(scene.current, camera)))
  return <scene ref={scene}>{/* ... */}</scene>
}

function Main() {
  const camera = useRef()
  const { width, height } = useThree().size
  return (
    <>
      <perspectiveCamera
        ref={camera}
        aspect={width / height}
        radius={(width + height) / 4}
        onUpdate={self => self.updateProjectionMatrix()}
      />
      {camera.current && (
        <group>
          <Content camera={camera.current} />
          <HeadsUpDisplay camera={camera.current} />
        </group>
      )}
    </>
  )
}

Managing imperative code

Stick imperative stuff into useMemo and write out everything else declaratively. This is how you can quickly form reactive, re-usable components that can be bound to a store, graphql, etc.

function Extrusion({ start = [0,0], paths, ...props }) {
  const shape = useMemo(() => {
    const shape = new THREE.Shape()
    shape.moveTo(...start)
    paths.forEach(path => shape.bezierCurveTo(...path))
    return shape
  }, [start, paths])

  return (
    <mesh>
      <extrudeGeometry attach="geometry" args={[shape, props]} />
      <meshPhongMaterial attach="material" />
    </mesh>
  )
}

Then ...

<Extrusion
  start={[25, 25]}
  paths={[
    [25, 25, 20, 0, 0, 0],
    [30, 0, 30, 35,30,35],
    [30, 55, 10, 77, 25, 95],
    [60, 77, 80, 55, 80, 35],
    [80, 35, 80, 0, 50, 0],
    [35, 0, 25, 25, 25, 25],
  ]}
  bevelEnabled
  amount={8}
  bevelSegments={2}
  steps={2}
  bevelSize={1}
  bevelThickness={1} />

ShaderMaterials

function CrossFade({ url1, url2, disp }) {
  const [texture1, texture2, dispTexture] = useMemo(() => {
    const loader = new THREE.TextureLoader()
    return [loader.load(url1), loader.load(url2), loader.load(disp)]
  }, [url1, url2, disp])
  return (
    <mesh>
      <planeBufferGeometry attach="geometry" args={[3.8, 3.8]} />
      <shaderMaterial
        attach="material"
        args={[CrossFadeShader]}
        uniforms-texture-value={texture1}
        uniforms-texture2-value={texture2}
        uniforms-disp-value={dispTexture}
        uniforms-dispFactor-value={0.5}
      />
    </mesh>
  )
}

Current Tags

6.0.0-alpha.11 ... alpha (4 years ago)
5.0.0-beta.12 ... beta (4 years ago)
0.0.0-deprecated ... deprecated (4 years ago)
6.0.13 ... latest (4 years ago)

284 Versions

6.0.13 [deprecated] ... 4 years ago
6.0.12 [deprecated] ... 4 years ago
6.0.11 [deprecated] ... 4 years ago
6.0.10 [deprecated] ... 4 years ago
5.3.22 [deprecated] ... 4 years ago
5.3.21 [deprecated] ... 4 years ago
5.3.20 [deprecated] ... 4 years ago
0.0.0-deprecated ... 4 years ago
6.0.0-alpha.11 ... 4 years ago
6.0.0-alpha.10 ... 4 years ago
6.0.0-alpha.9 ... 4 years ago
6.0.0-alpha.8 ... 4 years ago
6.0.0-alpha.7 ... 4 years ago
6.0.0-alpha.6 ... 4 years ago
6.0.0-alpha.5 ... 4 years ago
6.0.0-alpha.4 ... 4 years ago
6.0.0-alpha.3 ... 4 years ago
6.0.0-alpha.2 ... 4 years ago
6.0.0-alpha.1 ... 4 years ago
6.0.0-alpha.0 ... 4 years ago
5.3.19 [deprecated] ... 4 years ago
5.3.18 [deprecated] ... 4 years ago
5.3.17 [deprecated] ... 4 years ago
5.3.16 [deprecated] ... 4 years ago
5.3.15 [deprecated] ... 4 years ago
5.3.14 [deprecated] ... 4 years ago
5.3.13 [deprecated] ... 4 years ago
5.3.12 [deprecated] ... 4 years ago
5.3.11 [deprecated] ... 4 years ago
5.3.10 [deprecated] ... 4 years ago
5.3.9 [deprecated] ... 4 years ago
5.3.8 [deprecated] ... 4 years ago
5.3.7 [deprecated] ... 4 years ago
5.3.6 [deprecated] ... 4 years ago
5.3.5 [deprecated] ... 4 years ago
5.3.4 [deprecated] ... 4 years ago
5.3.3 [deprecated] ... 4 years ago
5.3.1 [deprecated] ... 4 years ago
5.3.0 [deprecated] ... 4 years ago
5.2.1 [deprecated] ... 4 years ago
5.2.0 [deprecated] ... 4 years ago
5.1.9 [deprecated] ... 4 years ago
5.1.8 [deprecated] ... 4 years ago
5.1.7 [deprecated] ... 4 years ago
5.1.6 [deprecated] ... 4 years ago
5.1.5 [deprecated] ... 4 years ago
5.1.4 [deprecated] ... 4 years ago
5.1.3 [deprecated] ... 4 years ago
5.1.2 [deprecated] ... 4 years ago
5.1.1 [deprecated] ... 4 years ago
5.1.0 [deprecated] ... 4 years ago
5.0.6 [deprecated] ... 4 years ago
5.0.5 [deprecated] ... 4 years ago
5.0.4 [deprecated] ... 4 years ago
5.0.3 [deprecated] ... 4 years ago
5.0.2 [deprecated] ... 4 years ago
5.0.1 [deprecated] ... 4 years ago
5.0.0 [deprecated] ... 4 years ago
5.0.0-beta.12 ... 4 years ago
4.2.21 [deprecated] ... 4 years ago
4.2.20 [deprecated] ... 4 years ago
5.0.0-alpha.1 ... 4 years ago
4.2.19 [deprecated] ... 4 years ago
4.2.18 [deprecated] ... 4 years ago
5.0.0-alpha.0 ... 4 years ago
5.0.0-beta.11 ... 4 years ago
4.2.17 [deprecated] ... 4 years ago
4.2.16 [deprecated] ... 4 years ago
4.2.15 [deprecated] ... 4 years ago
4.2.14 [deprecated] ... 4 years ago
4.2.13 [deprecated] ... 4 years ago
4.2.12 [deprecated] ... 5 years ago
4.2.11 [deprecated] ... 5 years ago
5.0.0-beta.10 ... 5 years ago
4.2.10 [deprecated] ... 5 years ago
4.2.9 [deprecated] ... 5 years ago
5.0.0-beta.8 ... 5 years ago
5.0.0-beta.7 ... 5 years ago
5.0.0-beta.6 ... 5 years ago
5.0.0-beta.5 ... 5 years ago
5.0.0-beta.4 ... 5 years ago
4.2.8 [deprecated] ... 5 years ago
5.0.0-beta.3 ... 5 years ago
5.0.0-beta.2 ... 5 years ago
5.0.0-beta.1 ... 5 years ago
4.2.7 [deprecated] ... 5 years ago
4.2.6 [deprecated] ... 5 years ago
5.0.0-beta.0 ... 5 years ago
4.2.5 [deprecated] ... 5 years ago
4.2.4 [deprecated] ... 5 years ago
4.2.3 [deprecated] ... 5 years ago
4.2.2 [deprecated] ... 5 years ago
4.2.0 [deprecated] ... 5 years ago
4.1.4 [deprecated] ... 5 years ago
4.1.3 [deprecated] ... 5 years ago
4.1.2 [deprecated] ... 5 years ago
4.1.1 [deprecated] ... 5 years ago
4.1.0 [deprecated] ... 5 years ago
4.0.29-beta.0 ... 5 years ago
4.0.28 [deprecated] ... 5 years ago
4.0.27 [deprecated] ... 5 years ago
4.0.26 [deprecated] ... 5 years ago
4.0.25 [deprecated] ... 5 years ago
4.0.24 [deprecated] ... 5 years ago
4.0.23 [deprecated] ... 5 years ago
4.0.22 [deprecated] ... 5 years ago
4.0.21 [deprecated] ... 5 years ago
4.0.21-beta.1 ... 5 years ago
4.0.21-beta.0 ... 5 years ago
4.0.20 [deprecated] ... 5 years ago
4.0.19 [deprecated] ... 5 years ago
4.0.18 [deprecated] ... 5 years ago
4.0.17 [deprecated] ... 5 years ago
4.0.16 [deprecated] ... 5 years ago
4.0.14 [deprecated] ... 5 years ago
4.0.13 [deprecated] ... 5 years ago
4.0.12 [deprecated] ... 5 years ago
4.0.11 [deprecated] ... 5 years ago
4.0.10 [deprecated] ... 5 years ago
4.0.9 [deprecated] ... 5 years ago
4.0.8 [deprecated] ... 5 years ago
4.0.7 [deprecated] ... 5 years ago
4.0.6 [deprecated] ... 5 years ago
4.0.5 [deprecated] ... 5 years ago
4.0.4 [deprecated] ... 5 years ago
4.0.3 [deprecated] ... 5 years ago
4.0.2 [deprecated] ... 5 years ago
4.0.1 [deprecated] ... 5 years ago
4.0.0-beta.16 ... 5 years ago
4.0.0-beta.15 ... 5 years ago
4.0.0-beta.14 ... 5 years ago
3.0.17 [deprecated] ... 5 years ago
4.0.0-beta.13 ... 5 years ago
4.0.0-beta.12 ... 5 years ago
3.0.16 [deprecated] ... 5 years ago
4.0.0-beta.11 ... 5 years ago
4.0.0-beta.10 ... 5 years ago
4.0.0-beta.9 ... 5 years ago
4.0.0-beta.8 ... 5 years ago
4.0.0-beta.7 ... 5 years ago
4.0.0-beta.6 ... 5 years ago
4.0.0-beta.5 ... 5 years ago
4.0.0-beta.4 ... 5 years ago
4.0.0-beta.3 ... 5 years ago
4.0.0-beta.2 ... 5 years ago
4.0.0-beta.1 ... 5 years ago
4.0.0-beta.0 ... 5 years ago
3.0.15 [deprecated] ... 5 years ago
3.0.14 [deprecated] ... 5 years ago
3.0.13 [deprecated] ... 5 years ago
3.0.12 [deprecated] ... 5 years ago
3.0.11 [deprecated] ... 5 years ago
3.0.10 [deprecated] ... 5 years ago
3.0.9 [deprecated] ... 5 years ago
3.0.8-beta.0 ... 5 years ago
3.0.8 [deprecated] ... 5 years ago
3.0.7 [deprecated] ... 5 years ago
3.0.6 [deprecated] ... 5 years ago
3.0.3 [deprecated] ... 5 years ago
3.0.2 [deprecated] ... 5 years ago
3.0.1 [deprecated] ... 5 years ago
3.0.0 [deprecated] ... 5 years ago
3.0.0-beta.16 ... 5 years ago
3.0.0-beta.15 ... 5 years ago
3.0.0-beta.14 ... 5 years ago
3.0.0-beta.13 ... 5 years ago
3.0.0-beta.12 ... 5 years ago
3.0.0-beta.11 ... 5 years ago
3.0.0-beta.10 ... 5 years ago
3.0.0-beta.9 ... 5 years ago
3.0.0-beta.8 ... 5 years ago
3.0.0-beta.7 ... 5 years ago
3.0.0-beta.6 ... 5 years ago
3.0.0-beta.4 ... 5 years ago
3.0.0-beta.3 ... 5 years ago
3.0.0-beta.1 ... 5 years ago
3.0.0-beta.0 ... 5 years ago
2.5.0-beta.1 ... 5 years ago
2.5.0-beta.0 ... 5 years ago
2.4.3 [deprecated] ... 5 years ago
2.4.2 [deprecated] ... 5 years ago
2.4.1 [deprecated] ... 5 years ago
2.4.0 [deprecated] ... 5 years ago
2.3.9 [deprecated] ... 5 years ago
2.3.8 [deprecated] ... 5 years ago
2.3.7 [deprecated] ... 5 years ago
2.3.6 [deprecated] ... 5 years ago
2.3.5 [deprecated] ... 5 years ago
2.3.4 [deprecated] ... 5 years ago
2.3.3-beta.0 ... 5 years ago
2.3.3 [deprecated] ... 5 years ago
2.3.2 [deprecated] ... 5 years ago
2.3.1 [deprecated] ... 5 years ago
2.3.0 [deprecated] ... 5 years ago
2.2.17-beta.2 ... 5 years ago
2.2.17-beta.1 ... 5 years ago
2.2.17-beta.0 ... 5 years ago
2.2.17 [deprecated] ... 5 years ago
2.2.16 [deprecated] ... 5 years ago
2.2.15 [deprecated] ... 5 years ago
2.2.14 [deprecated] ... 5 years ago
2.2.13 [deprecated] ... 5 years ago
2.2.12 [deprecated] ... 5 years ago
2.2.11 [deprecated] ... 5 years ago
2.2.10 [deprecated] ... 5 years ago
2.2.9 [deprecated] ... 6 years ago
2.2.8 [deprecated] ... 6 years ago
2.2.7 [deprecated] ... 6 years ago
2.2.6 [deprecated] ... 6 years ago
2.2.5 [deprecated] ... 6 years ago
2.2.4 [deprecated] ... 6 years ago
2.2.3 [deprecated] ... 6 years ago
2.2.2 [deprecated] ... 6 years ago
2.2.1 [deprecated] ... 6 years ago
2.2.0 [deprecated] ... 6 years ago
2.1.6 [deprecated] ... 6 years ago
2.1.5 [deprecated] ... 6 years ago
2.1.4 [deprecated] ... 6 years ago
2.1.3-beta.0 ... 6 years ago
2.1.3 [deprecated] ... 6 years ago
2.1.2 [deprecated] ... 6 years ago
2.1.1 [deprecated] ... 6 years ago
2.1.0 [deprecated] ... 6 years ago
2.1.0-beta.2 ... 6 years ago
2.1.0-beta.1 ... 6 years ago
2.1.0-beta.0 ... 6 years ago
2.0.12 [deprecated] ... 6 years ago
2.0.11 [deprecated] ... 6 years ago
2.0.10 [deprecated] ... 6 years ago
2.0.9 [deprecated] ... 6 years ago
2.0.8 [deprecated] ... 6 years ago
2.0.7 [deprecated] ... 6 years ago
2.0.6 [deprecated] ... 6 years ago
2.0.5 [deprecated] ... 6 years ago
2.0.4 [deprecated] ... 6 years ago
2.0.3 [deprecated] ... 6 years ago
2.0.2 [deprecated] ... 6 years ago
2.0.1 [deprecated] ... 6 years ago
2.0.0 [deprecated] ... 6 years ago
2.0.0-beta.12 ... 6 years ago
2.0.0-beta.11 ... 6 years ago
2.0.0-beta.10 ... 6 years ago
2.0.0-beta.9 ... 6 years ago
2.0.0-beta.8 ... 6 years ago
2.0.0-beta.7 ... 6 years ago
2.0.0-beta.6 ... 6 years ago
2.0.0-beta.5 ... 6 years ago
2.0.0-beta.4 ... 6 years ago
2.0.0-beta.3 ... 6 years ago
2.0.0-beta.2 ... 6 years ago
2.0.0-beta.1 ... 6 years ago
1.5.4-beta.0 ... 6 years ago
1.5.3 [deprecated] ... 6 years ago
1.5.2 [deprecated] ... 6 years ago
1.5.1 [deprecated] ... 6 years ago
1.5.0 [deprecated] ... 6 years ago
1.4.0-beta.1 ... 6 years ago
1.4.0-beta.0 ... 6 years ago
1.3.10 [deprecated] ... 6 years ago
1.3.9-beta.1 ... 6 years ago
1.3.9 [deprecated] ... 6 years ago
1.3.8 [deprecated] ... 6 years ago
1.3.7 [deprecated] ... 6 years ago
1.3.6 [deprecated] ... 6 years ago
1.3.5 [deprecated] ... 6 years ago
1.3.4 [deprecated] ... 6 years ago
1.3.3 [deprecated] ... 6 years ago
1.3.2 [deprecated] ... 6 years ago
1.3.1 [deprecated] ... 6 years ago
1.3.0-beta.0 ... 6 years ago
1.3.0 [deprecated] ... 6 years ago
1.2.7 [deprecated] ... 6 years ago
1.2.4 [deprecated] ... 6 years ago
1.2.2 [deprecated] ... 6 years ago
1.2.1 [deprecated] ... 6 years ago
1.2.0 [deprecated] ... 6 years ago
1.1.0 [deprecated] ... 6 years ago
1.0.8 [deprecated] ... 6 years ago
1.0.7 [deprecated] ... 6 years ago
1.0.6 [deprecated] ... 6 years ago
1.0.5 [deprecated] ... 6 years ago
1.0.4 [deprecated] ... 6 years ago
1.0.3 [deprecated] ... 6 years ago
1.0.2 [deprecated] ... 6 years ago