Repository files navigation

react-three-fiber is aReact renderer for threejs.

Build your scene declaratively with re-usable, self-contained components that react to state, are readily interactive and can participate in React's ecosystem.

npm install three @types/three @react-three/fiber

None. Everything that works in Threejs will work here without exception.

No. There is no overhead. Components render outside of React. It outperforms Threejs in scale due to React's scheduling abilities.

Yes. It merely expresses Threejs in JSX,<mesh /> dynamically turns intonew THREE.Mesh(). If a new Threejs version adds, removes or changes features, it will be available to you instantly without depending on updates to this library.

Let's make a re-usable component that has its own state, reacts to user-input and participates in the render-loop. (live demo).

import{createRoot}from'react-dom/client'importReact,{useRef,useState}from'react'import{Canvas,useFrame}from'@react-three/fiber'functionBox(props){// This reference gives us direct access to the THREE.Mesh objectconstref=useRef()// Hold state for hovered and clicked eventsconst[hovered,hover]=useState(false)const[clicked,click]=useState(false)// Subscribe this component to the render-loop, rotate the mesh every frameuseFrame((state,delta)=>(ref.current.rotation.x+=delta))// Return the view, these are regular Threejs elements expressed in JSXreturn(<mesh{...props}ref={ref}scale={clicked ?1.5 :1}onClick={(event)=>click(!clicked)}onPointerOver={(event)=>hover(true)}onPointerOut={(event)=>hover(false)}><boxGeometryargs={[1,1,1]}/><meshStandardMaterialcolor={hovered ?'hotpink' :'orange'}/></mesh>)}createRoot(document.getElementById('root')).render(<Canvas><ambientLightintensity={Math.PI/2}/><spotLightposition={[10,10,10]}angle={0.15}penumbra={1}decay={0}intensity={Math.PI}/><pointLightposition={[-10,-10,-10]}decay={0}intensity={Math.PI}/><Boxposition={[-1.2,0,0]}/><Boxposition={[1.2,0,0]}/></Canvas>,)

npm install @types/three

import*asTHREEfrom'three'import{createRoot}from'react-dom/client'importReact,{useRef,useState}from'react'import{Canvas,useFrame,ThreeElements}from'@react-three/fiber'functionBox(props:ThreeElements['mesh']){constref=useRef<THREE.Mesh>(null!)const[hovered,hover]=useState(false)const[clicked,click]=useState(false)useFrame((state,delta)=>(ref.current.rotation.x+=delta))return(<mesh{...props}ref={ref}scale={clicked ?1.5 :1}onClick={(event)=>click(!clicked)}onPointerOver={(event)=>hover(true)}onPointerOut={(event)=>hover(false)}><boxGeometryargs={[1,1,1]}/><meshStandardMaterialcolor={hovered ?'hotpink' :'orange'}/></mesh>)}createRoot(document.getElementById('root')asHTMLElement).render(<Canvas><ambientLightintensity={Math.PI/2}/><spotLightposition={[10,10,10]}angle={0.15}penumbra={1}decay={0}intensity={Math.PI}/><pointLightposition={[-10,-10,-10]}decay={0}intensity={Math.PI}/><Boxposition={[-1.2,0,0]}/><Boxposition={[1.2,0,0]}/></Canvas>,)

# Install expo-cli, this will create our appnpm install expo-cli -g# Create app and cd into itexpo init my-appcd my-app# Install dependenciesnpm install three @react-three/fiber@beta react@rc# Startexpo start

// metro.config.jsmodule.exports={resolver:{sourceExts:['js','jsx','json','ts','tsx','cjs'],assetExts:['glb','png','jpg'],},}

importReact,{useRef,useState}from'react'import{Canvas,useFrame}from'@react-three/fiber/native'functionBox(props){constmesh=useRef(null)const[hovered,setHover]=useState(false)const[active,setActive]=useState(false)useFrame((state,delta)=>(mesh.current.rotation.x+=delta))return(<mesh{...props}ref={mesh}scale={active ?1.5 :1}onClick={(event)=>setActive(!active)}onPointerOver={(event)=>setHover(true)}onPointerOut={(event)=>setHover(false)}><boxGeometryargs={[1,1,1]}/><meshStandardMaterialcolor={hovered ?'hotpink' :'orange'}/></mesh>)}exportdefaultfunctionApp(){return(<Canvas><ambientLightintensity={Math.PI/2}/><spotLightposition={[10,10,10]}angle={0.15}penumbra={1}decay={0}intensity={Math.PI}/><pointLightposition={[-10,-10,-10]}decay={0}intensity={Math.PI}/><Boxposition={[-1.2,0,0]}/><Boxposition={[1.2,0,0]}/></Canvas>)}

Visitdocs.pmnd.rs

You need to be versed in both React and Threejs before rushing into this. If you are unsure about React consult the officialReact docs, especiallythe section about hooks. As for Threejs, make sure you at least glance over the following links:

1. Make sure you have abasic grasp of Threejs. Keep that site open.
2. When you know what a scene is, a camera, mesh, geometry, material, fork thedemo above.
3. Look up the JSX elements that you see (mesh, ambientLight, etc),all threejs exports are native to three-fiber.
4. Try changing some values, scroll through ourAPI to see what the various settings and hooks do.

Some helpful material:

• Threejs-docs andexamples
• Discover Threejs, especially theTips and Tricks chapter for best practices
• Bruno Simons Threejs Jouney, arguably the best learning resource, now includes a fullR3F chapter

There is a vibrant and extensive eco system around three-fiber, full of libraries, helpers and abstractions.

• @react-three/drei – useful helpers, this is an eco system in itself
• @react-three/gltfjsx – turns GLTFs into JSX components
• @react-three/postprocessing – post-processing effects
• @react-three/uikit – WebGL rendered UI components for three-fiber
• @react-three/test-renderer – for unit tests in node
• @react-three/offscreen – offscreen/worker canvas for react-three-fiber
• @react-three/flex – flexbox for react-three-fiber
• @react-three/xr – VR/AR controllers and events
• @react-three/csg – constructive solid geometry
• @react-three/rapier – 3D physics using Rapier
• @react-three/cannon – 3D physics using Cannon
• @react-three/p2 – 2D physics using P2
• @react-three/a11y – real a11y for your scene
• @react-three/gpu-pathtracer – realistic path tracing
• create-r3f-app next – nextjs starter
• lamina – layer based shader materials
• zustand – flux based state management
• jotai – atoms based state management
• valtio – proxy based state management
• react-spring – a spring-physics-based animation library
• framer-motion-3d – framer motion, a popular animation library
• use-gesture – mouse/touch gestures
• leva – create GUI controls in seconds
• maath – a kitchen sink for math helpers
• miniplex – ECS (entity management system)
• composer-suite – composing shaders, particles, effects and game mechanics
• triplex – visual editor for react-three-fiber
• koestlich – UI component library for react-three-fiber

Usage Trend of the @react-three Family

A small selection of companies and projects relying on three-fiber.

• vercel (design agency)
• basement (design agency)
• studio freight (design agency)
• 14 islands (design agency)
• ueno (design agency) —video
• flux.ai (PCB builder)
• colorful.app (modeller)
• bezi (modeller)
• readyplayer.me (avatar configurator)
• zillow (real estate)
• lumalabs.ai/genie (AI models)
• skybox.blockadelabs (AI envmaps)
• 3dconfig (floor planer)
• buerli.io (CAD)
• getencube (CAD)
• glowbuzzer (CAD) —video
• triplex (editor) —video
• theatrejs (editor) —video

If you like this project, please consider helping out. All contributions are welcome as well as donations toOpencollective, or in cryptoBTC: 36fuguTPxGCNnYZSRdgdh6Ea94brCAjMbH,ETH: 0x6E3f79Ea1d0dcedeb33D3fC6c34d2B1f156F2682.

Thank you to all our backers! 🙏

This project exists thanks to all the people who contribute.