Your first scene

This tutorial will assume some React knowledge.

We'll start by importing the <Canvas /> component from @react-three/fiber and putting it in our React tree.

import { createRoot } from 'react-dom/client'
import { Canvas } from '@react-three/fiber'

function App() {
  return (
    <div id="canvas-container">
      <Canvas />
    </div>
  )
}

createRoot(document.getElementById('root')).render(<App />)

The Canvas component does some important setup work behind the scenes:

To actually see something in our scene, we'll add a lowercase <mesh /> native element, which is the direct equivalent to new THREE.Mesh().

<Canvas>
  <mesh />

A Mesh is a basic scene object in three.js, and it's used to hold the geometry and the material needed to represent a shape in 3D space. We'll create a new mesh using a BoxGeometry and a MeshStandardMaterial which automatically attach to their parent.

<Canvas>
  <mesh>
    <boxGeometry />
    <meshStandardMaterial />
  </mesh>
</Canvas>

Let's pause for a moment to understand exactly what is happening here. The code we just wrote is the equivalent to this three.js code:

const scene = new THREE.Scene()
const camera = new THREE.PerspectiveCamera(75, width / height, 0.1, 1000)

const renderer = new THREE.WebGLRenderer()
renderer.setSize(width, height)
document.querySelector('#canvas-container').appendChild(renderer.domElement)

const mesh = new THREE.Mesh()
mesh.geometry = new THREE.BoxGeometry()
mesh.material = new THREE.MeshStandardMaterial()

scene.add(mesh)

function animate() {
  requestAnimationFrame(animate)
  renderer.render(scene, camera)
}

animate()

According to the docs for BoxGeometry we can optionally pass three arguments for: width, length and depth:

new THREE.BoxGeometry(2, 2, 2)

In order to do this in Fiber we use the args prop, which always takes an array whose items represent the constructor arguments.

<boxGeometry args={[2, 2, 2]} />

Next, we will add some lights to our scene, by putting these components into our canvas.

<Canvas>
  <ambientLight intensity={0.1} />
  <directionalLight color="red" position={[0, 0, 5]} />

This introduces us to the last fundamental concept of Fiber, how React props work on three.js objects. When you set any prop on a Fiber component, it will set the property of the same name on the three.js instance.

Let's focus on our ambientLight, whose documentation tells us that we can optionally construct it with a color, but it can also receive props.

<ambientLight intensity={0.1} />

Which is the equivalent to:

const light = new THREE.AmbientLight()
light.intensity = 0.1

There are a few shortcuts for props that have a .set() method (colors, vectors, etc).

const light = new THREE.DirectionalLight()
light.position.set(0, 0, 5)
light.color.set('red')

Which is the same as the following in JSX:

<directionalLight position={[0, 0, 5]} color="red" />

Please refer to the API for a deeper explanation.

import { Canvas } from "@react-three/fiber";

export default function App() {
return (
    <Canvas>
      <mesh>
        <boxGeometry args={[2, 2, 2]} />
        <meshPhongMaterial />
      </mesh>
      <ambientLight intensity={0.1} />
      <directionalLight position={[0, 0, 5]} color="red" />
    </Canvas>
);
}