Guide · Open source

How to use react-three-fiber: install, build a 3D scene and respond to clicks

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

react-three-fiber (published as @react-three/fiber) is a React renderer for Three.js, the JavaScript library for 3D graphics in the browser. Instead of writing imperative Three.js code, you describe your scene with JSX elements such as mesh and ambientLight. This guide covers installation, the version pairing with React, a working interactive example, and when a different tool makes more sense.

react-three-fiberpmndrs/react-three-fiber · ★ 33.4k · MIT Install options & downloads

Quick start

1Check your React version. Confirm whether your project uses React 18 or React 19, since that decides which @react-three/fiber major version to install.
2Install the packages. Run npm install three @types/three @react-three/fiber in your project.
3Create a Canvas. Import Canvas from @react-three/fiber and place it in your component tree to hold the 3D scene.
4Add lights and meshes. Place ambientLight, spotLight or pointLight, and mesh elements with a geometry and material inside the Canvas.
5Make a component with state. Wrap a mesh in your own component, use useState for hover or click state and attach onClick or onPointerOver props.
6Animate with useFrame. Use useFrame inside the component to change the mesh's rotation or other properties on each frame.

What react-three-fiber is and who it suits

react-three-fiber is a React renderer for Three.js. You build a scene from re-usable components that can hold state, react to user input and take part in React's ecosystem.

It suits React developers adding 3D to a web app, and developers who already know Three.js and want a component-based structure. It is not a good first step if you are new to both React and Three.js, because the project itself says you should be versed in both before starting.

Good fit: 3D scenes inside a React web app
Good fit: 3D objects that respond to clicks, hover or state changes
Not a fit: projects that do not use React, since it needs React to run

Install react-three-fiber with the right React version

Install Three.js, its types and react-three-fiber with your package manager. The README gives this command.

The package must match your React major version. @react-three/fiber@8 pairs with react@18, and @react-three/fiber@9 pairs with react@19. Check your React version before you install, so you do not mix incompatible versions.

Prerequisites: Node.js and React
v8 of @react-three/fiber needs React 18
v9 of @react-three/fiber needs React 19

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

Build your first 3D scene with a Canvas and JSX elements

Wrap your scene in a Canvas component. Inside it, Three.js classes are written as JSX elements: mesh becomes a Three.js Mesh, and ambientLight, spotLight and pointLight add lights. The README notes that <mesh /> turns into new THREE.Mesh().

The example below renders two boxes. It uses createRoot from react-dom/client to mount the app on an element with the id root.

import { createRoot } from 'react-dom/client'
import React, { useRef, useState } from 'react'
import { Canvas, useFrame } from '@react-three/fiber'

function Box(props) {
  // This reference gives us direct access to the THREE.Mesh object
  const ref = useRef()
  // Hold state for hovered and clicked events
  const [hovered, hover] = useState(false)
  const [clicked, click] = useState(false)
  // Subscribe this component to the render-loop, rotate the mesh every frame
  useFrame((state, delta) => (ref.current.rotation.x += delta))
  // Return the view, these are regular Threejs elements expressed in JSX
  return (
    <mesh
      {...props}
      ref={ref}
      scale={clicked ? 1.5 : 1}
      onClick={(event) => click(!clicked)}
      onPointerOver={(event) => hover(true)}
      onPointerOut={(event) => hover(false)}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color={hovered ? 'hotpink' : 'orange'} />
    </mesh>
  )
}

createRoot(document.getElementById('root')).render(
  <Canvas>
    <ambientLight intensity={Math.PI / 2} />
    <spotLight position={[10, 10, 10]} angle={0.15} penumbra={1} decay={0} intensity={Math.PI} />
    <pointLight position={[-10, -10, -10]} decay={0} intensity={Math.PI} />
    <Box position={[-1.2, 0, 0]} />
    <Box position={[1.2, 0, 0]} />
  </Canvas>,
)

Use TypeScript with react-three-fiber

The README includes a TypeScript version of the same example. It imports Three.js types, uses ThreeElements['mesh'] for the props type of the component, and casts the root element to HTMLElement.

If you need the types, install @types/three, which is also part of the main install command.

Type the component props with ThreeElements['mesh']
Type the mesh ref with THREE.Mesh

import * as THREE from 'three'
import { createRoot } from 'react-dom/client'
import React, { useRef, useState } from 'react'
import { Canvas, useFrame, ThreeElements } from '@react-three/fiber'

function Box(props: ThreeElements['mesh']) {
  const ref = 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)}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color={hovered ? 'hotpink' : 'orange'} />
    </mesh>
  )
}

createRoot(document.getElementById('root') as HTMLElement).render(
  <Canvas>
    <ambientLight intensity={Math.PI / 2} />
    <spotLight position={[10, 10, 10]} angle={0.15} penumbra={1} decay={0} intensity={Math.PI} />
    <pointLight position={[-10, -10, -10]} decay={0} intensity={Math.PI} />
    <Box position={[-1.2, 0, 0]} />
    <Box position={[1.2, 0, 0]} />
  </Canvas>,
)

Animate objects with useFrame and handle pointer events

useFrame subscribes a component to the render loop. The example uses it to rotate a mesh every frame by the delta value. A ref gives you direct access to the underlying THREE.Mesh object.

Pointer props such as onClick, onPointerOver and onPointerOut update React state, and that state changes the mesh's scale and color. This is how 3D objects respond to clicks and hover.

useFrame((state, delta) => ...) runs on each frame
onClick, onPointerOver and onPointerOut handle input
Changing state updates scale and color on the mesh

Learn Three.js alongside react-three-fiber

The project recommends a basic grasp of Three.js before you start. Scene, camera, mesh, geometry and material are the core ideas. Look up each JSX element in the Three.js docs, since all Three.js exports are available in react-three-fiber.

The README also lists the official docs at docs.pmnd.rs, the Three.js manual and examples, and Bruno Simon's Three.js Journey, which includes an R3F chapter.

Three.js manual: threejs.org/manual
Official react-three-fiber docs: docs.pmnd.rs/react-three-fiber
Three.js Journey course, which includes an R3F chapter

Know the React Native option

The README includes a React Native example. It imports Canvas from @react-three/fiber/native and relies on React 18. It also says some Metro bundler configuration is needed if you load assets with useLoader or Drei helpers such as useGLTF and useTexture. The README's React Native steps use the expo-cli tool.

What people use it for

Interactive product viewers where an object changes color or scale on hover or click
Animated 3D objects inside a React web app that respond to component state
Reusable 3D components built with the same patterns as other React components
Browser-based 3D scenes that use Three.js features directly through JSX

Frequently asked questions

Is react-three-fiber free to use?

react-three-fiber is released under the MIT licence, according to the project's repository. The MIT licence permits use, modification and distribution, so check its terms for your own project.

Which React version do I need for react-three-fiber?

Use @react-three/fiber@8 with react@18, or @react-three/fiber@9 with react@19. The project says the renderer must pair with a major version of React, like react-dom or react-native.

Does react-three-fiber support everything Three.js does?

The README says everything that works in Three.js works here, and that Three.js classes map directly onto JSX elements. New Three.js features are usable without waiting for an update to this library.

Is react-three-fiber slower than plain Three.js?

The README says there is no overhead, because components render outside of React. It also says the library can outperform Three.js at scale due to React's scheduling abilities.

Can I use react-three-fiber without React?

No. It is a React renderer and needs React to run. If your project does not use React, the README points to using Three.js directly.

What are the alternatives to react-three-fiber?

The project's comparable tools are Three.js used directly without React, Babylon.js and PlayCanvas. Choose Three.js directly if you do not use React, and consider the others if you need a different engine.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

react-three-fiber suits React developers who want 3D scenes in a web app, especially if they already know Three.js. If you are new to both React and Three.js, learn the basics of each first, and if you do not use React, use Three.js directly or another engine such as Babylon.js or PlayCanvas.

Install options & downloads