These demos are real, click them!

npm install react-three-fiber

React-three-fiber is a small React renderer for THREE-js. Driving THREE as a render-target makes just as much sense as it makes for the DOM. Building a complex scene graph becomes easier because it can be componentized declaratively with clean, reactive semantics. This also opens up the eco system, you can now apply generic packages for state, animation, gestures, etc.

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

We ship a small reconciler config with a few additions for interaction. It does not know or care about THREE deeply, it uses heuristics to support attributes generically, so we can get away without creating a strong dependency. Hooks of course hold it all together. The aforementioned libs served as an inspiration.

How it looks like ...

import { Canvas } from 'react-three-fiber'

function Thing({ vertices, color }) {
  return (
    <group ref={ref => console.log('we have access to the instance')}>
      <line position={[10, 20, 30]} rotation={[THREE.Math.degToRad(90), 0, 0]}>
        <geometry
          name="geometry"
          vertices={vertices.map(v => new THREE.Vector3(...v))}
          onUpdate={self => (self.verticesNeedUpdate = true)}
        />
        <lineBasicMaterial name="material" color={color} />
      </line>
      <mesh
        onClick={e => console.log('click')}
        onHover={e => console.log('hover')}
        onUnhover={e => console.log('unhover')}>
        <octahedronGeometry name="geometry" />
        <meshStandardMaterial name="material" color="grey" opacity={0.5} transparent />
      </mesh>
    </group>
  )
}

ReactDOM.render(
  <Canvas>
    <Thing color="blue" vertices={[[-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. If you give them a name they attach 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 name="geometry" args={[1, 16, 16]} />
  <meshStandardMaterial name="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 name="material">
  <texture
    name="map"
    format={THREE.RGBFormat}
    image={img}
    onUpdate={self => img && (self.needsUpdate = true)} />
</meshBasicMaterial>

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 msh = new THREE.Mesh()
return <primitive object={msh} />

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.

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

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

Dealing with effects (hijacking main render-loop)

import { apply, Canvas, useRender, useThree } from 'react-three-fiber'
import { EffectComposer } from './impl/postprocessing/EffectComposer'
import { RenderPass } from './impl/postprocessing/RenderPass'
import { GlitchPass } from './impl/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.width, size.height])
  // 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 name="passes" args={[scene, camera]} />
      <glitchPass name="passes" renderToScreen factor={factor} />
    </effectComposer>
  )
}

Heads-up display (rendering multiple scenes)

function Hud() {
  const scene = useRef()
  const hud = useRef()

  const cam = useRef()
  const { size: { aspect, width, height} } = useThree()
  const [data, set] = useState({ aspect: 0, radius: 0 })
  useEffect(() => void set({ aspect, radius: (width + height) / 4 }), [width, height])
  
  // This takes over as the main render-loop (when 2nd arg is set to true)
  useRender(({ gl }) => {
    gl.autoClear = true
    gl.render(scene.current, cam.current)
    gl.autoClear = false
    gl.clearDepth()
    gl.render(hud.current, cam.current)
  }, true)

  return (
    <>
      <scene ref={scene}>
        <perspectiveCamera
          {...data}
          ref={cam}
          position={[0, 0, 5]}
          onUpdate={self => self.updateProjectionMatrix()} />
        {/* Main scene ... */}
      </scene>
      <scene ref={hud}>
        {/* This scene will be projected on top... */}
      </scene>
    </>
  )
}

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