react-three-fiber is a React reconciler for Threejs on the web and react-native.
npm install three react-three-fiber
These demos are real, you can click them! They contain the full code, too.
Building dynamic scene graphs declaratively with re-usable components makes dealing with Threejs easier and brings order and sanity to your codebase. These components react to state changes, are interactive out of the box and can tap into Reacts infitine eco system.
None. Everything that works in Threejs will work here. In contrast to "bindings" where a library ships/maintains dozens of wrapper components, it just reconciles JSX to Threejs dynamically: <mesh /> simply is another expression for new THREE.Mesh(). It does not know or target a specific Threejs version nor does it need updates for modified, added or removed upstream features.
No. Rendering performance is up to Threejs and the GPU. Components may participate in the renderloop outside of React, without any additional overhead. React is otherwise very efficient in building and managing component-trees, it could potentially outperform manual/imperative apps at scale.
| Let's make a re-usable component that has it's own state, reacts to user-input and participates in the render-loop: |  |
import ReactDOM from 'react-dom'
import React, { useRef, useState } from 'react'
import { Canvas, useFrame } from 'react-three-fiber'
function Box(props) {
// This reference will give us direct access to the mesh
const mesh = useRef()
// Set up state for the hovered and active state
const [hovered, setHover] = useState(false)
const [active, setActive] = useState(false)
// Rotate mesh every frame, this is outside of React without overhead
useFrame(() => (mesh.current.rotation.x = mesh.current.rotation.y += 0.01))
return (
<mesh
{...props}
ref={mesh}
scale={active ? [1.5, 1.5, 1.5] : [1, 1, 1]}
onClick={e => setActive(!active)}
onPointerOver={e => setHover(true)}
onPointerOut={e => setHover(false)}>
<boxBufferGeometry attach="geometry" args={[1, 1, 1]} />
<meshStandardMaterial attach="material" color={hovered ? 'hotpink' : 'orange'} />
</mesh>
)
}
ReactDOM.render(
<Canvas>
<ambientLight />
<pointLight position={[10, 10, 10]} />
<Box position={[-1.2, 0, 0]} />
<Box position={[1.2, 0, 0]} />
</Canvas>,
document.getElementById('root')
)Here's the same running in a code sandbox.
- Before you start, make sure you have a basic grasp of Threejs.
- When you know what a scene is, a camera, mesh, geometry and material, more or less, fork the sandbox above.
- Robert Borghesi's (@dghez_) Alligator.io tutorial will lead you through the next steps.
You can advance your knowledge by reading into Threejs-fundamentals and Discover Threejs. Here are some general do's and don't for performance and best practices. Looking into the source of the original threejs-examples couldn't hurt.
The Canvas object is your portal into Threejs. It renders Threejs elements, not DOM elements! It stretches to 100% of the next relative/absolute parent-container. Make sure your canvas is given space to show contents!
<Canvas
children // Either a function child (which receives state) or regular children
gl // Props that go into the default webGL-renderer
camera // Props that go into the default camera
raycaster // Props that go into the default raycaster
shadowMap // Props that go into gl.shadowMap, can also be set true for PCFsoft
sRGB = false // Sets encoding to sRGBEncoding, tonemapping to ACESFilmicToneMapping
vr = false // Switches renderer to VR mode, then uses gl.setAnimationLoop
gl2 = false // Enables webgl2
concurrent = false // Enables React concurrent mode
resize = undefined // Resize config, see react-use-measure's options
orthographic = false // Creates an orthographic camera if true
noEvents = false // Switch off raytracing and event support
pixelRatio = undefined // You could provide window.devicePixelRatio if you like
invalidateFrameloop = false // When true it only renders on changes, when false it's a game loop
updateDefaultCamera = true // Adjusts default camera on size changes
onCreated // Callback when vdom is ready (you can block first render via promise)
onPointerMissed /> // Response for pointer clicks that have missed a targetYou can give it additional properties like style and className, which will be added to the container (a div) that holds the dom-canvas element.
Canvas will create a translucent WebGL-renderer with the following properties: antialias, alpha, setClearAlpha(0)
A default perspective camera: fov: 75, near: 0.1, far: 1000, z: 5, lookAt: [0,0,0]
A default orthographic camera if Canvas.orthographic is true: near: 0.1, far: 1000, z: 5, lookAt: [0,0,0]
A default shadowMap if Canvas.shadowMap is true: type: PCFSoftShadowMap
A default scene (into which all the JSX is rendered) and a raycaster.
A wrapping container with a resize observer: scroll: true, debounce: { scroll: 50, resize: 0 }
You do not have to use any of these objects, look under "Recipes" down below if you want to bring your own.
You can use Threejs's entire object catalogue and all properties. When in doubt, always consult the docs.
You could lay out an object like this:
<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('hotpink'), transparent: true })}
/>The problem is that all of these properties will always be re-created. Instead, you should define properties declaratively.
<mesh visible userData={{ test: 'hello' }} position={[1, 2, 3]} rotation={[0, 0, 0]}>
<sphereGeometry attach="geometry" args={[1, 16, 16]} />
<meshStandardMaterial attach="material" color="hotpink" transparent />
</mesh>All properties that have a .set() method can be given a shortcut. For example THREE.Color.set can take a color string, hence instead of color={new THREE.Color('hotpink')} you can do color="hotpink". Some set methods take multiple arguments (THREE.Vector3.set), so you can pass an array position={[100, 0, 0]}.
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 objects bind automatically to their parent and are taken off it once they unmount.
You can nest primitive objects, too:
<meshBasicMaterial attach="material">
<texture attach="map" image={img} onUpdate={self => img && (self.needsUpdate = true)} />Sometimes attaching isn't enough. For example, this code attaches effects to an array called "passes" of the parent effectComposer. Note the use of attachArray which adds the object to the target array and takes it out on unmount:
<effectComposer>
<renderPass attachArray="passes" scene={scene} camera={camera} />
<glitchPass attachArray="passes" renderToScreen />You can also attach to named parent properties using attachObject={[target, name]}, which adds the object and takes it out on unmount. The following adds a buffer-attribute to parent.attributes.position.
<bufferGeometry attach="geometry">
<bufferAttribute attachObject={['attributes', 'position']} count={v.length / 3} array={v} itemSize={3} />If you want to reach into nested attributes (for instance: mesh.rotation.x), just use dash-case:
<mesh rotation-x={1} material-uniforms-resolution-value={[1 / size.width, 1 / size.height]} />You can use the primitive placeholder for that. You can still give it properties or attach nodes to it. Never add the same object multiples times, this is not allowed in Threejs!
const mesh = new THREE.Mesh()
return <primitive object={mesh} position={[0, 0, 0]} />The extend function extends three-fibers catalogue of known native JSX elements.
import { extend } from 'react-three-fiber'
import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer'
import { RenderPass } from 'three/examples/jsm/postprocessing/RenderPass'
extend({ EffectComposer, RenderPass })
<effectComposer>
<renderPass />Freeing resources is a manual chore in Threejs, but react is aware of object-lifecycles, hence three-fiber will attempt to free resources for you by calling object.dispose() (if present) on all unmounted objects.
If you manage assets by yourself, globally or in a cache, this may not be what you want. You can recursively switch it off:
const globalGeometry = new THREE.BoxBufferGeometry()
const globalMaterial = new THREE.MeshBasicMatrial()
function Mesh() {
return <mesh geometry={globalGeometry} material={globalMaterial} dispose={null} />Threejs objects that implement their own raycast method (meshes, lines, etc) can be interacted with by declaring events on the object. We support pointer events (you need to polyfill them yourself), clicks and wheel-scroll. Events contain the browser event as well as the Threejs event data (object, point, distance, etc).
Additionally there's a special onUpdate that is called every time the object gets fresh props, which is good for things like self => (self.verticesNeedUpdate = true).
<mesh
onClick={e => console.log('click')}
onWheel={e => console.log('wheel spins')}
onPointerUp={e => console.log('up')}
onPointerDown={e => console.log('down')}
onPointerOver={e => console.log('over')}
onPointerOut={e => console.log('out')}
onPointerEnter={e => console.log('enter')}
onPointerLeave={e => console.log('leave')}
onPointerMove={e => console.log('move')}
onUpdate={self => console.log('props have been updated')}
/>({
...DomEvent // All the original event data
...ThreeEvent // All of Three's intersection data
object: Object3D // The object that was actually hit
eventObject: Object3D // The object that registered the event
unprojectedPoint: Vector3 // Camera-unprojected point
ray: Ray // The ray that was used to strike the object
camera: Camera // The camera that was used in the raycaster
sourceEvent: DomEvent // A reference to the host event
delta: number // Initial-click delta
}) => ... onPointerDown={e => {
// Only the mesh closest to the camera will be processed
e.stopPropagation()
// You may optionally capture the target
e.target.setPointerCapture(e.pointerId)
}}
onPointerUp={e => {
e.stopPropagation()
// Optionally release capture
e.target.releasePointerCapture(e.pointerId)
}}Hooks can only be used inside the Canvas element because they rely on context! You cannot expect something like this to work:
function App() {
const { size } = useThree() // This will just crash
return (
<Canvas>
<mesh>Do this instead:
function SomeComponent() {
const { size } = useThree()
return <mesh />
}
function App() {
return (
<Canvas>
<SomeComponent />This hooks gives you access to all the basic objects that are kept internally, like the default renderer, scene, camera. It also gives you the current size of the canvas in screen and viewport coordinates. The hook is reactive, if you resize the browser, for instance, and you get fresh measurements, same applies to any of the defaults you can change.
import { useThree } from 'react-three-fiber'
const {
gl, // WebGL renderer
scene, // Default scene
camera, // Default camera
size, // Bounds of the view (which stretches 100% and auto-adjusts)
viewport, // Bounds of the viewport in 3d units + factor (size/viewport)
aspect, // Aspect ratio (size.width / size.height)
mouse, // Current 2D mouse coordinates
clock, // THREE.Clock (useful for useFrame deltas)
invalidate, // Invalidates a single frame (for <Canvas invalidateFrameloop />)
intersect, // Calls onMouseMove handlers for objects underneath the cursor
setDefaultCamera, // Sets the default camera
} = useThree()This hooks calls you back every frame, which is good for running effects, updating controls, etc. You receive the state (same as useThree) and a clock delta. If you supply a render priority greater than zero it will switch off automatic rendering entirely, you can then control rendering yourself. If you have multiple frames with a render priority then they are ordered highest priority last, similar to the web's z-index. Frames are managed, three-fiber will remove them automatically when the component that holds them is unmounted.
Updating controls:
import { useFrame } from 'react-three-fiber'
const controls = useRef()
useFrame(state => controls.current.update())
return <orbitControls ref={controls} />Taking over the render-loop:
useFrame(({ gl, scene, camera }) => gl.render(scene, camera), 1)When you want to share and re-use resources. useResource creates a ref and re-renders the component when it becomes available next frame.
import { useResource } from 'react-three-fiber'
const [ref, material] = useResource()
return (
<meshBasicMaterial ref={ref} />
{material && (
<mesh material={material} />
<mesh material={material} />
<mesh material={material} />When objects need to be updated imperatively.
import { useUpdate } from 'react-three-fiber'
const ref = useUpdate(
geometry => {
geometry.addAttribute('position', getVertices(x, y, z))
geometry.attributes.position.needsUpdate = true
},
[x, y, z] // execute only if these properties change
)
return <bufferGeometry ref={ref} />This hooks loads assets and suspends for easier fallback- and error-handling. If you need to lay out GLTF's declaratively check out gltfjsx.
import React, { Suspense } from 'react'
import { useLoader } from 'react-three-fiber'
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'
function Asset({ url }) {
const gltf = useLoader(GLTFLoader, url)
return <primitive object={gltf.scene} dispose={null} />
}
<Suspense fallback={<Cube />}>
<Asset url="/spaceship.gltf" />
</Suspense>You can provide a callback if you need to configure your loader:
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader'
useLoader(GLTFLoader, url, loader => {
const dracoLoader = new DRACOLoader()
dracoLoader.setDecoderPath('/draco-gltf/')
loader.setDRACOLoader(dracoLoader)
})It can also make multiple requests in parallel:
const [bumpMap, specMap, normalMap] = useLoader(TextureLoader, [url1, url2, url2])This is a special purpose hook for the rare case when you are using non-default cameras for heads-up-displays or portals, and you need events/raytracing to function properly (raycasting uses the default camera otherwise).
import { useCamera } from 'react-three-fiber'
<mesh raycast={useCamera(customCamera)} onPointerMove={e => console.log('move')}>import {
addEffect, // Adds a global callback which is called each frame
addTail, // Adds a global callback which is called when rendering stops
invalidate, // Forces view global invalidation
extend, // Extends the native-object catalogue
createPortal, // Creates a portal (it's a React feature for re-parenting)
render, // Internal: Renders three jsx into a scene
unmountComponentAtNode, // Internal: Unmounts root scene
applyProps, // Internal: Sets element properties
Dom, // Project HTML content
} from 'react-three-fiber'Sometimes you want to project dom-content on top (or underneath) of the canvas. The experimental Dom component behaves like an empty THREE.Group internally, you can transform and nest it inside the canvas. It's children on the other hand will be rendered into a div element and projected to the groups whereabouts.
<Dom
children // Regular dom content, text, images, divs, etc
prepend = false // Will be projected in front of the canvas
center = false // Adds a -50%/-50% css transform
style // Regular css styles, will be added to the inner div container
className // ..
onClick // ..
... />import { Canvas, Dom } from 'react-three-fiber'
<Canvas>
<Dom position={[100, 0, 100]}>
<h1>hello world!</h1>
</Dom>
</Canvas>News and examples via Twitter: @0xca0a
Recipes and FAQ: /react-three-fiber/recipes.md
GLTF-to-JSX converter: https://github.com/react-spring/gltfjsx
If you like this project, please consider helping out. All contributions are welcome as well as donations to Opencollective, or in crypto:
BTC: 36fuguTPxGCNnYZSRdgdh6Ea94brCAjMbH
ETH: 0x6E3f79Ea1d0dcedeb33D3fC6c34d2B1f156F2682
Thank you to all our backers! 🙏
This project exists thanks to all the people who contribute.
