React Three Fiber

Full documentation content.

<page path="/getting-started/introduction" title="Introduction"><![CDATA[URL: https://r3f.docs.pmnd.rs/getting-started/introduction
Description: React-three-fiber is a React renderer for three.js.


<Intro>
  Build your scene declaratively with re-usable, self-contained components that react to state, are readily interactive and can participate in [React](https://react.dev)'s ecosystem.
</Intro>

[![React Three Fiber banner](../banner-r3f.jpg)](/getting-started/examples)

```bash
npm install three @types/three @react-three/fiber
```
> [!WARNING]  
> Three-fiber is a React renderer, it must pair with a major version of React, just like react-dom, react-native, etc. @react-three/fiber@8 pairs with react@18, @react-three/fiber@9 pairs with react@19.

## Does it have limitations?

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

## Is it slower than plain Threejs?

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

## Can it keep up with frequent feature updates to Threejs?

Yes. It merely expresses Threejs in JSX, `<mesh />` dynamically turns into `new 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.

## What does it look like?

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

<Sandpack
  customSetup={{
    dependencies: {
      'react': 'latest',
      'react-dom': 'latest',
      'three': 'latest',
      '@react-three/fiber': 'latest'
    },
    entry: '/index.jsx',
  }}
  folder="basic-example-sandpack"
/>

<details>
  <summary>Show TypeScript example</summary>

```bash
npm install @types/three
```

<Sandpack
  customSetup={{
    dependencies: {
      'react': 'latest',
      'react-dom': 'latest',
      'three': 'latest',
      '@types/three': 'latest',
      '@react-three/fiber': 'latest'
    },
    entry: '/index.tsx',
    main: '/index.tsx',
  }}
  files={{
    '/styles.css': `html,body,#root {height:100%;margin:unset;}`,
    '/index.tsx': `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'
import './styles.css'

function Box(props: ThreeElements['mesh']) {
  const meshRef = useRef<THREE.Mesh>(null!)
  const [hovered, setHover] = useState(false)
  const [active, setActive] = useState(false)
  useFrame((state, delta) => (meshRef.current.rotation.x += delta))
  return (
    <mesh
      {...props}
      ref={meshRef}
      scale={active ? 1.5 : 1}
      onClick={(event) => setActive(!active)}
      onPointerOver={(event) => setHover(true)}
      onPointerOut={(event) => setHover(false)}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color={hovered ? 'hotpink' : '#2f74c0'} />
    </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>,
)`,
  }}
/>

</details>

<details>
  <summary>Show React Native example</summary>

For installation instructions see [react native installation instructions](/getting-started/installation#react-native).

```jsx
import React, { useRef, useState } from 'react'
import { Canvas, useFrame } from '@react-three/fiber/native'

function Box(props) {
  const meshRef = useRef(null)
  const [hovered, setHover] = useState(false)
  const [active, setActive] = useState(false)
  useFrame((state, delta) => (meshRef.current.rotation.x += delta))
  return (
    <mesh
      {...props}
      ref={meshRef}
      scale={active ? 1.5 : 1}
      onClick={(event) => setActive(!active)}
      onPointerOver={(event) => setHover(true)}
      onPointerOut={(event) => setHover(false)}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color={hovered ? 'hotpink' : 'orange'} />
    </mesh>
  )
}

export default function App() {
  return (
    <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>
  )
}
```

</details>

## First steps

You need to be versed in both React and Threejs before rushing into this. If you are unsure about React consult the official [React docs](https://react.dev/learn), especially [the section about hooks](https://react.dev/reference/react). As for Threejs, make sure you at least glance over the following links:

1. Make sure you have a [basic grasp of Threejs](https://threejs.org/docs/index.html#manual/en/introduction/Creating-a-scene). Keep that site open.
2. When you know what a scene is, a camera, mesh, geometry, material, fork the [demo above](https://github.com/pmndrs/react-three-fiber#what-does-it-look-like).
3. [Look up](https://threejs.org/docs/index.html#api/en/objects/Mesh) the JSX elements that you see (mesh, ambientLight, etc), _all_ threejs exports are native to three-fiber.
4. Try changing some values, scroll through our [API](/api/canvas) to see what the various settings and hooks do.

Some helpful material:

- [Threejs-docs](https://threejs.org/docs) and [examples](https://threejs.org/examples)
- [Discover Threejs](https://discoverthreejs.com), especially the [Tips and Tricks](https://discoverthreejs.com/tips-and-tricks) chapter for best practices
- [Bruno Simons Threejs Journey](https://threejs-journey.com), arguably the best learning resource, now includes a full [R3F chapter](https://threejs-journey.com/lessons/what-are-react-and-react-three-fiber)

<a href="https://threejs-journey.com">
  <img src="../banner-journey.jpg" />
</a>

## Ecosystem

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

- [`@react-three/drei`](https://github.com/pmndrs/drei) &ndash; useful helpers, this is an ecosystem in itself
- [`@react-three/gltfjsx`](https://github.com/pmndrs/gltfjsx) &ndash; turns GLTFs into JSX components
- [`@react-three/postprocessing`](https://github.com/pmndrs/react-postprocessing) &ndash; post-processing effects
- [`@react-three/test-renderer`](https://github.com/pmndrs/react-three-fiber/tree/master/packages/test-renderer) &ndash; for unit tests in node
- [`@react-three/flex`](https://github.com/pmndrs/react-three-flex) &ndash; flexbox for react-three-fiber
- [`@react-three/xr`](https://github.com/pmndrs/react-xr) &ndash; VR/AR controllers and events
- [`@react-three/csg`](https://github.com/pmndrs/react-three-csg) &ndash; constructive solid geometry
- [`@react-three/rapier`](https://github.com/pmndrs/react-three-rapier) &ndash; 3D physics using Rapier
- [`@react-three/cannon`](https://github.com/pmndrs/use-cannon) &ndash; 3D physics using Cannon
- [`@react-three/p2`](https://github.com/pmndrs/use-p2) &ndash; 2D physics using P2
- [`@react-three/a11y`](https://github.com/pmndrs/react-three-a11y) &ndash; real a11y for your scene
- [`@react-three/gpu-pathtracer`](https://github.com/pmndrs/react-three-gpu-pathtracer) &ndash; realistic path tracing
- [`create-r3f-app next`](https://github.com/pmndrs/react-three-next) &ndash; nextjs starter
- [`lamina`](https://github.com/pmndrs/lamina) &ndash; layer based shader materials
- [`zustand`](https://github.com/pmndrs/zustand) &ndash; flux based state management
- [`jotai`](https://github.com/pmndrs/jotai) &ndash; atoms based state management
- [`valtio`](https://github.com/pmndrs/valtio) &ndash; proxy based state management
- [`react-spring`](https://github.com/pmndrs/react-spring) &ndash; a spring-physics-based animation library
- [`framer-motion-3d`](https://www.framer.com/docs/three-introduction/) &ndash; framer motion, a popular animation library
- [`use-gesture`](https://github.com/pmndrs/react-use-gesture) &ndash; mouse/touch gestures
- [`leva`](https://github.com/pmndrs/leva) &ndash; create GUI controls in seconds
- [`maath`](https://github.com/pmndrs/maath) &ndash; a kitchen sink for math helpers
- [`miniplex`](https://github.com/hmans/miniplex) &ndash; ECS (entity management system)
- [`composer-suite`](https://github.com/hmans/composer-suite) &ndash; composing shaders, particles, effects and game mechanics

## How to contribute

If you like this project, please consider helping out. All contributions are welcome as well as donations to [Opencollective](https://opencollective.com/react-three-fiber), or in crypto `BTC: 36fuguTPxGCNnYZSRdgdh6Ea94brCAjMbH`, `ETH: 0x6E3f79Ea1d0dcedeb33D3fC6c34d2B1f156F2682`.

## Backers

Thank you to all our backers! 🙏

<a href="https://opencollective.com/react-three-fiber#backers" target="_blank">
  <img src="https://opencollective.com/react-three-fiber/backers.svg?width=890" width="890" height="207" />
</a>

## Contributors

This project exists thanks to all the people who contribute.

<a href="https://github.com/pmndrs/react-three-fiber/graphs/contributors">
  <img src="https://opencollective.com/react-three-fiber/contributors.svg?width=890" width="890" height="411" />
</a>
]]></page>
<page path="/getting-started/installation" title="Installation"><![CDATA[URL: https://r3f.docs.pmnd.rs/getting-started/installation
Description: Learn how to install react-three-fiber


```bash
npm install three @react-three/fiber
```

> [!WARNING]  
> Fiber is compatible with React v18 and v19 and works with ReactDOM and React Native. Fiber is a React renderer, it must pair with a major version of React, just like react-dom, react-native, etc. @react-three/fiber@8 pairs with react@18, @react-three/fiber@9 pairs with react@19.

Getting started with React Three Fiber is not nearly as hard as you might have thought, but various frameworks may require particular attention.

We've put together guides for getting started with each popular framework:

- Vite.js
- Next.js
- CDN w/o build tools
- React Native

If you just want to give it a try, fork this [example on codesandbox](https://codesandbox.io/s/rrppl0y8l4?file=/src/App.js)!

## Vite.js

`vite` will also work out of the box.

```bash
# Create app
npm create vite my-app

# Select react as framework

# Install dependencies
cd my-app
npm install three @react-three/fiber

# Start development server
npm run dev
```

## Next.js

It should work out of the box but you will encounter untranspiled add-ons in the three.js ecosystem, in that case,

### Next.js 13.1 or latest version

You need to add three to `transpilePackages` property in `next.config.js`:

```js
transpilePackages: ['three'],
```

### Next.js 13.0 or oldest version

You can install the `next-transpile-modules` module:

```bash
npm install next-transpile-modules --save-dev
```

then, add this to your `next.config.js`

```js
const withTM = require('next-transpile-modules')(['three'])
module.exports = withTM()
```

Make sure to check out our [official next.js starter](https://github.com/pmndrs/react-three-next), too!

## Without build tools

You can use React Three Fiber with browser-ready ES Modules from [esm.sh](https://esm.sh) and a JSX-like syntax powered by [htm](https://github.com/developit/htm).

```jsx
import ReactDOM from 'https://esm.sh/react-dom'
import React, { useRef, useState } from 'https://esm.sh/react'
import { Canvas, useFrame } from 'https://esm.sh/@react-three/fiber'
import htm from 'https://esm.sh/htm'

const html = htm.bind(React.createElement)
ReactDOM.render(html`<${Canvas}>...<//>`, document.getElementById('root'))
```

<details>
<summary>Full example</summary>

```jsx
import ReactDOM from 'https://esm.sh/react-dom'
import React, { useRef, useState } from 'https://esm.sh/react'
import { Canvas, useFrame } from 'https://esm.sh/@react-three/fiber'
import htm from 'https://esm.sh/htm'

const html = htm.bind(React.createElement)

function Box(props) {
  const meshRef = useRef()
  const [hovered, setHover] = useState(false)
  const [active, setActive] = useState(false)
  useFrame(() => (meshRef.current.rotation.x = meshRef.current.rotation.y += 0.01))
  return html` <mesh
    ...${props}
    ref=${meshRef}
    scale=${active ? 1.5 : 1}
    onClick=${() => setActive(!active)}
    onPointerOver=${() => setHover(true)}
    onPointerOut=${() => setHover(false)}
  >
    <boxGeometry args=${[1, 1, 1]} />
    <meshStandardMaterial color=${hovered ? 'hotpink' : 'orange'} />
  </mesh>`
}

ReactDOM.render(
  html` <${Canvas}>
    <ambientLight />
    <pointLight position=${[10, 10, 10]} />
    <${Box} position=${[-1.2, 0, 0]} />
    <${Box} position=${[1.2, 0, 0]} />
  <//>`,
  document.getElementById('root'),
)
```

</details>

## React Native

R3F v8 adds support for react-native and can be imported from `@react-three/fiber/native`. We use `expo-gl` and `expo-asset` under the hood for WebGL2 bindings and ensuring interplay between Metro and three.js loaders.

To get started, create an app via `expo` or `react-native`:

```bash
# Create a managed/bare app
npx create-expo-app
cd my-app

# or

# Create and link bare app
npx react-native init my-app
npx install-expo-modules@latest
cd my-app
```

Then install dependencies (for manual installation or migration, see [expo modules installation](https://docs.expo.dev/bare/installing-expo-modules)):

```bash
# Automatically install
expo install expo-gl

# Install NPM dependencies
npm install three @react-three/fiber
```

Some configuration may be required to tell the Metro bundler about your assets if you use `useLoader` or Drei abstractions like `useGLTF` and `useTexture`:

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

R3F's API is completely x-platform, so you can use [events](/api/events) and [hooks](/api/hooks) just as you would on the web.

> [!NOTE]
> Make sure to import from `@react-three/fiber/native` or `@react-three/drei/native` for correct IntelliSense and platform-specific abstractions.

> [!NOTE]
> iOS simulators often have incomplete or unreliable OpenGL ES support, which can cause EXC_BAD_ACCESS crashes when rendering 3D content. Always test on a physical iOS device (iPhone/iPad running iOS 16 or later) to ensure stable WebGL rendering.

```jsx
import { Suspense } from 'react'
import { Canvas } from '@react-three/fiber/native'
import { useGLTF } from '@react-three/drei/native'
import modelPath from './path/to/model.glb'

function Model(props) {
  const gltf = useGLTF(modelPath)
  return <primitive {...props} object={gltf.scene} />
}

export default function App() {
  return (
    <Canvas>
      <ambientLight />
      <Suspense>
        <Model />
      </Suspense>
    </Canvas>
  )
}
```
]]></page>
<page path="/getting-started/your-first-scene" title="Your first scene"><![CDATA[URL: https://r3f.docs.pmnd.rs/getting-started/your-first-scene
Description: This guide will help you setup your first React Three Fiber scene and introduce you to its core concepts.


This tutorial will assume some React knowledge.

## Setting up the Canvas

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

```jsx
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:

- It sets up a **Scene** and a **Camera**, the basic building blocks necessary for rendering
- It renders our scene every frame, you do not need a traditional render-loop

> [!NOTE]
> Canvas is responsive to fit the parent node, so you can control how big it is by changing the parents width and height, in this case #canvas-container.

## Adding a Mesh Component

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

```js
<Canvas>
  <mesh />
```

> [!NOTE]
> Note that we don't need to import anything, All three.js objects will be treated as native JSX elements, just like you can just write &lt;div /&gt; or &lt;span /&gt; in regular ReactDOM. The general rule is that Fiber components are available under the camel-case version of their name in three.js.

A [`Mesh`](https://threejs.org/docs/#api/en/objects/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](/api/objects#attach) to their parent.

```jsx
<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:

```jsx
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()
```

### Constructor arguments

According to the [docs for `BoxGeometry`](https://threejs.org/docs/#api/en/geometries/BoxGeometry) we can optionally pass three arguments for: width, length and depth:

```js
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.

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

> [!NOTE]
> Note that every time you change args, the object must be re-constructed!

## Adding lights

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

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

### Props

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](https://threejs.org/docs/#api/en/lights/AmbientLight) tells us that we can optionally construct it with a color, but it can also receive props.

```jsx
<ambientLight intensity={0.1} />
```

Which is the equivalent to:

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

### Shortcuts

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

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

Which is the same as the following in JSX:

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

Please refer to the API for [a deeper explanation](/api/objects).

## The result

<Sandpack
  template="react"
  customSetup={{
    dependencies: {
      'react': 'latest',
      'react-dom': 'latest',
      'three': 'latest',
      '@types/three': 'latest',
      '@react-three/fiber': 'latest'
    },
  }}
  files={{
    '/styles.css': `html,body,#root {height:100%;margin:unset;}`,
    '/App.js': `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>
  );
}`,
  }}
/>

> [!TIP]
> You can live-edit the code above:
> - try different materials, like [`MeshNormalMaterial`](https://threejs.org/docs/#api/en/materials/MeshNormalMaterial) or [`MeshBasicMaterial`](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial), give them a color
> - try different geometries, like [`SphereGeometry`](https://threejs.org/docs/#api/en/geometries/SphereGeometry) or [`OctahedronGeometry`](https://threejs.org/docs/#api/en/geometries/OctahedronGeometry)
> - try changing the `position` on our `mesh` component, by setting the prop with the same name
> - try extracting our mesh to a new component
]]></page>
<page path="/getting-started/examples" title="Examples"><![CDATA[URL: https://r3f.docs.pmnd.rs/getting-started/examples
Description: A few examples that demonstrate what you can do with React Three Fiber


## Showcase

<Grid cols={1}>
  <li>
    <p>[![shopping demo](https://pmndrs.github.io/examples/shopping/thumbnail.webp)](https://pmndrs.github.io/examples/shopping) -- <span>selection</span>, <span>tiltshift</span></p>
  </li>
</Grid>
<Grid cols={2}>
  <li>
    <p>[![cards-with-border-radius demo](https://pmndrs.github.io/examples/cards-with-border-radius/thumbnail.webp)](https://pmndrs.github.io/examples/cards-with-border-radius) -- <span>border-radius</span></p>
  </li>
  <li>
    <p>[![threejs-journey-lv-1-fisheye demo](https://pmndrs.github.io/examples/threejs-journey-lv-1-fisheye/thumbnail.webp)](https://pmndrs.github.io/examples/threejs-journey-lv-1-fisheye) -- <span>bruno</span>, <span>simon</span>, <span>threejs-journey</span>, <span>fisheye</span></p>
  </li>
  <li>
    <p>[![lusion-connectors demo](https://pmndrs.github.io/examples/lusion-connectors/thumbnail.webp)](https://pmndrs.github.io/examples/lusion-connectors) -- <span>lusion</span>, <span>n8ao</span></p>
  </li>
  <li>
    <p>[![ecctrl-fisheye demo](https://pmndrs.github.io/examples/ecctrl-fisheye/thumbnail.webp)](https://pmndrs.github.io/examples/ecctrl-fisheye) -- <span>ecctrl</span>, <span>character-controller</span></p>
  </li>
  <li>
    <p>[![monitors demo](https://pmndrs.github.io/examples/monitors/thumbnail.webp)](https://pmndrs.github.io/examples/monitors) -- <span>effects</span>, <span>bloom</span>, <span>dof</span>, <span>reflections</span></p>
  </li>
  <li>
    <p>[![flying-bananas demo](https://pmndrs.github.io/examples/flying-bananas/thumbnail.webp)](https://pmndrs.github.io/examples/flying-bananas) -- <span>effects</span>, <span>dof</span>, <span>bananas</span></p>
  </li>
  <li>
    <p>[![t-shirt-configurator demo](https://pmndrs.github.io/examples/t-shirt-configurator/thumbnail.webp)](https://pmndrs.github.io/examples/t-shirt-configurator) -- <span>configurator</span>, <span>t-shirt</span>, <span>soft-shadows</span></p>
  </li>
  <li>
    <p>[![caustics demo](https://pmndrs.github.io/examples/caustics/thumbnail.webp)](https://pmndrs.github.io/examples/caustics) -- <span>caustics</span>, <span>effects</span>, <span>soft-shadows</span></p>
  </li>
</Grid>
<Grid cols={4}>
  <li>
    <p>[![ssgi-spheres-with-rapier-physics demo](https://pmndrs.github.io/examples/ssgi-spheres-with-rapier-physics/thumbnail.webp)](https://pmndrs.github.io/examples/ssgi-spheres-with-rapier-physics) -- <span>ssgi</span>, <span>rapier</span></p>
  </li>
  <li>
    <p>[![thunder-clouds demo](https://pmndrs.github.io/examples/thunder-clouds/thumbnail.webp)](https://pmndrs.github.io/examples/thunder-clouds) -- <span>clouds</span></p>
  </li>
  <li>
    <p>[![motionpathcontrols demo](https://pmndrs.github.io/examples/motionpathcontrols/thumbnail.webp)](https://pmndrs.github.io/examples/motionpathcontrols) -- <span>motion-path</span>, <span>clouds</span></p>
  </li>
  <li>
    <p>[![room-with-soft-shadows demo](https://pmndrs.github.io/examples/room-with-soft-shadows/thumbnail.webp)](https://pmndrs.github.io/examples/room-with-soft-shadows) -- <span>caustics</span>, <span>effects</span>, <span>soft-shadows</span></p>
  </li>
  <li>
    <p>[![volumetric-light-godray demo](https://pmndrs.github.io/examples/volumetric-light-godray/thumbnail.webp)](https://pmndrs.github.io/examples/volumetric-light-godray) -- <span>godrays</span>, <span>reflections</span></p>
  </li>
  <li>
    <p>[![enter-portals demo](https://pmndrs.github.io/examples/enter-portals/thumbnail.webp)](https://pmndrs.github.io/examples/enter-portals) -- <span>portals</span></p>
  </li>
  <li>
    <p>[![pass-through-portals demo](https://pmndrs.github.io/examples/pass-through-portals/thumbnail.webp)](https://pmndrs.github.io/examples/pass-through-portals) -- <span>portals</span></p>
  </li>
  <li>
    <p>[![magic-box demo](https://pmndrs.github.io/examples/magic-box/thumbnail.webp)](https://pmndrs.github.io/examples/magic-box) -- <span>portals</span></p>
  </li>
  <li>
    <p>[![video-cookies demo](https://pmndrs.github.io/examples/video-cookies/thumbnail.webp)](https://pmndrs.github.io/examples/video-cookies) -- <span>video</span>, <span>cookies</span>, <span>caustics</span></p>
  </li>
  <li>
    <p>[![glass-flower demo](https://pmndrs.github.io/examples/glass-flower/thumbnail.webp)](https://pmndrs.github.io/examples/glass-flower) -- <span>glass</span>, <span>transmission</span>, <span>bloom</span></p>
  </li>
  <li>
    <p>[![cards demo](https://pmndrs.github.io/examples/cards/thumbnail.webp)](https://pmndrs.github.io/examples/cards) -- <span>cards</span>, <span>image</span></p>
  </li>
  <li>
    <Codesandbox id="3ywzzx" tags={['refraction']} />
  </li>
  <li>
    <p>[![image-gallery demo](https://pmndrs.github.io/examples/image-gallery/thumbnail.webp)](https://pmndrs.github.io/examples/image-gallery) -- <span>reflections</span>, <span>annotations</span></p>
  </li>
  <li>
    <p>[![horizontal-tiles demo](https://pmndrs.github.io/examples/horizontal-tiles/thumbnail.webp)](https://pmndrs.github.io/examples/horizontal-tiles) -- <span>scroll</span>, <span>controls</span></p>
  </li>
  <li>
    <p>[![bestservedbold-christmas-baubles demo](https://pmndrs.github.io/examples/bestservedbold-christmas-baubles/thumbnail.webp)](https://pmndrs.github.io/examples/bestservedbold-christmas-baubles) -- <span>physics</span></p>
  </li>
  <li>
    <p>[![the-three-graces demo](https://pmndrs.github.io/examples/the-three-graces/thumbnail.webp)](https://pmndrs.github.io/examples/the-three-graces) -- <span>html</span>, <span>annotations</span></p>
  </li>
  <li>
    <p>[![frosted-glass demo](https://pmndrs.github.io/examples/frosted-glass/thumbnail.webp)](https://pmndrs.github.io/examples/frosted-glass) -- <span>frosted</span>, <span>glass</span>, <span>transmission</span></p>
  </li>
  <li>
    <p>[![gltfjsx-400kb-drone demo](https://pmndrs.github.io/examples/gltfjsx-400kb-drone/thumbnail.webp)](https://pmndrs.github.io/examples/gltfjsx-400kb-drone) -- <span>gltfjsx</span>, <span>effects</span>, <span>bloom</span>, <span>soft-shadows</span></p>
  </li>
  <li>
    <p>[![starwars demo](https://pmndrs.github.io/examples/starwars/thumbnail.webp)](https://pmndrs.github.io/examples/starwars) -- <span>effects</span>, <span>reflections</span>, <span>ssr</span>, <span>bloom</span></p>
  </li>
  <li>
    <p>[![bruno-simons-20k-challenge demo](https://pmndrs.github.io/examples/bruno-simons-20k-challenge/thumbnail.webp)](https://pmndrs.github.io/examples/bruno-simons-20k-challenge) -- <span>rapier</span>, <span>physics</span>, <span>soft-shadows</span></p>
  </li>
  <li>
    <p>[![scrollcontrols-and-lens-refraction demo](https://pmndrs.github.io/examples/scrollcontrols-and-lens-refraction/thumbnail.webp)](https://pmndrs.github.io/examples/scrollcontrols-and-lens-refraction) -- <span>scroll</span>, <span>refraction</span>, <span>lens</span></p>
  </li>
  <li>
    <p>[![building-dynamic-envmaps demo](https://pmndrs.github.io/examples/building-dynamic-envmaps/thumbnail.webp)](https://pmndrs.github.io/examples/building-dynamic-envmaps) -- <span>effects</span>, <span>bloom</span>, <span>reflections</span></p>
  </li>
  <li>
    <p>[![nextjs-prism demo](https://pmndrs.github.io/examples/nextjs-prism/thumbnail.webp)](https://pmndrs.github.io/examples/nextjs-prism) -- <span>effects</span>, <span>bloom</span></p>
  </li>
  <li>
    <p>[![building-live-envmaps demo](https://pmndrs.github.io/examples/building-live-envmaps/thumbnail.webp)](https://pmndrs.github.io/examples/building-live-envmaps) -- <span>custom</span>, <span>environments</span></p>
  </li>
  <li>
    <p>[![shoe-configurator demo](https://pmndrs.github.io/examples/shoe-configurator/thumbnail.webp)](https://pmndrs.github.io/examples/shoe-configurator) -- <span>gltfjsx</span>, <span>configurator</span></p>
  </li>
  <li>
    <p>[![audio-analyser demo](https://pmndrs.github.io/examples/audio-analyser/thumbnail.webp)](https://pmndrs.github.io/examples/audio-analyser) -- <span>audio</span>, <span>analyser</span></p>
  </li>
  <li>
    <p>[![ground-reflections-and-video-textures demo](https://pmndrs.github.io/examples/ground-reflections-and-video-textures/thumbnail.webp)](https://pmndrs.github.io/examples/ground-reflections-and-video-textures) -- <span>ground</span>, <span>reflections</span>, <span>video-texture</span></p>
  </li>
  <li>
    <p>[![threejs-journey-portal demo](https://pmndrs.github.io/examples/threejs-journey-portal/thumbnail.webp)](https://pmndrs.github.io/examples/threejs-journey-portal) -- <span>bruno-simon</span>, <span>threejs-journey</span></p>
  </li>
  <li>
    <p>[![mixing-html-and-webgl-w-occlusion demo](https://pmndrs.github.io/examples/mixing-html-and-webgl-w-occlusion/thumbnail.webp)](https://pmndrs.github.io/examples/mixing-html-and-webgl-w-occlusion) -- <span>html</span>, <span>iframe</span></p>
  </li>
  <li>
    <p>[![interactive-spline-scene-live-html demo](https://pmndrs.github.io/examples/interactive-spline-scene-live-html/thumbnail.webp)](https://pmndrs.github.io/examples/interactive-spline-scene-live-html) -- <span>splinetool</span>, <span>iframe</span></p>
  </li>
  <li>
    <p>[![diamond-refraction demo](https://pmndrs.github.io/examples/diamond-refraction/thumbnail.webp)](https://pmndrs.github.io/examples/diamond-refraction) -- <span>refraction</span></p>
  </li>
  <li>
    <p>[![diamond-ring demo](https://pmndrs.github.io/examples/diamond-ring/thumbnail.webp)](https://pmndrs.github.io/examples/diamond-ring) -- <span>refraction</span>, <span>instanced</span></p>
  </li>
  <li>
    <p>[![envmap-ground-projection demo](https://pmndrs.github.io/examples/envmap-ground-projection/thumbnail.webp)](https://pmndrs.github.io/examples/envmap-ground-projection) -- <span>ground-projected-env</span></p>
  </li>
  <li>
    <p>[![spline-glass-shapes demo](https://pmndrs.github.io/examples/spline-glass-shapes/thumbnail.webp)](https://pmndrs.github.io/examples/spline-glass-shapes) -- <span>splinetool</span>, <span>transmission</span></p>
  </li>
  <li>
    <p>[![csg-bunny-usegroups demo](https://pmndrs.github.io/examples/csg-bunny-usegroups/thumbnail.webp)](https://pmndrs.github.io/examples/csg-bunny-usegroups) -- <span>transmission</span>, <span>csg</span></p>
  </li>
  <li>
    <p>[![csg-house demo](https://pmndrs.github.io/examples/csg-house/thumbnail.webp)](https://pmndrs.github.io/examples/csg-house) -- <span>csg</span></p>
  </li>
  <li>
    <p>[![gltf-animations-tied-to-scroll demo](https://pmndrs.github.io/examples/gltf-animations-tied-to-scroll/thumbnail.webp)](https://pmndrs.github.io/examples/gltf-animations-tied-to-scroll) -- <span>scroll</span>, <span>animation</span>, <span>effects</span>, <span>tiltshift</span></p>
  </li>
  <li>
    <p>[![object-clump demo](https://pmndrs.github.io/examples/object-clump/thumbnail.webp)](https://pmndrs.github.io/examples/object-clump) -- <span>physics</span>, <span>effects</span>, <span>n8ao</span></p>
  </li>
  <li>
    <p>[![html-input-fields demo](https://pmndrs.github.io/examples/html-input-fields/thumbnail.webp)](https://pmndrs.github.io/examples/html-input-fields) -- <span>html</span>, <span>input</span></p>
  </li>
  <li>
    <p>[![useintersect-and-scrollcontrols demo](https://pmndrs.github.io/examples/useintersect-and-scrollcontrols/thumbnail.webp)](https://pmndrs.github.io/examples/useintersect-and-scrollcontrols) -- <span>scroll</span></p>
  </li>
  <li>
    <p>[![infinite-scroll demo](https://pmndrs.github.io/examples/infinite-scroll/thumbnail.webp)](https://pmndrs.github.io/examples/infinite-scroll) -- <span>scroll</span></p>
  </li>
  <li>
    <p>[![scrollcontrols-with-minimap demo](https://pmndrs.github.io/examples/scrollcontrols-with-minimap/thumbnail.webp)](https://pmndrs.github.io/examples/scrollcontrols-with-minimap) -- <span>scroll</span></p>
  </li>
  <li>
    <p>[![instanced-particles-effects demo](https://pmndrs.github.io/examples/instanced-particles-effects/thumbnail.webp)](https://pmndrs.github.io/examples/instanced-particles-effects) -- <span>effects</span>, <span>particles</span></p>
  </li>
  <li>
    <p>[![dbismut-furniture demo](https://pmndrs.github.io/examples/dbismut-furniture/thumbnail.webp)](https://pmndrs.github.io/examples/dbismut-furniture) -- <span>cross-fade</span>, <span>transitions</span></p>
  </li>
  <li>
    <p>[![portal-shapes demo](https://pmndrs.github.io/examples/portal-shapes/thumbnail.webp)](https://pmndrs.github.io/examples/portal-shapes) -- <span>transmission</span>, <span>portals</span>, <span>physics</span></p>
  </li>
  <li>
    <p>[![aquarium demo](https://pmndrs.github.io/examples/aquarium/thumbnail.webp)](https://pmndrs.github.io/examples/aquarium) -- <span>transmission</span>, <span>portals</span></p>
  </li>
  <li>
    <p>[![portals demo](https://pmndrs.github.io/examples/portals/thumbnail.webp)](https://pmndrs.github.io/examples/portals) -- <span>portals</span>, <span>blend</span></p>
  </li>
  <li>
    <p>[![inter-epoxy-resin demo](https://pmndrs.github.io/examples/inter-epoxy-resin/thumbnail.webp)](https://pmndrs.github.io/examples/inter-epoxy-resin)</p>
  </li>
  <li>
    <p>[![stage-presets-gltfjsx demo](https://pmndrs.github.io/examples/stage-presets-gltfjsx/thumbnail.webp)](https://pmndrs.github.io/examples/stage-presets-gltfjsx)</p>
  </li>
  <li>
    <p>[![react-ellipsecurve demo](https://pmndrs.github.io/examples/react-ellipsecurve/thumbnail.webp)](https://pmndrs.github.io/examples/react-ellipsecurve)</p>
  </li>
  <li>
    <p>[![iridescent-decals demo](https://pmndrs.github.io/examples/iridescent-decals/thumbnail.webp)](https://pmndrs.github.io/examples/iridescent-decals)</p>
  </li>
  <li>
    <p>[![baking-soft-shadows demo](https://pmndrs.github.io/examples/baking-soft-shadows/thumbnail.webp)](https://pmndrs.github.io/examples/baking-soft-shadows)</p>
  </li>
  <li>
    <p>[![ssr-test demo](https://pmndrs.github.io/examples/ssr-test/thumbnail.webp)](https://pmndrs.github.io/examples/ssr-test)</p>
  </li>
  <li>
    <p>[![csg-operations-rapier-physics demo](https://pmndrs.github.io/examples/csg-operations-rapier-physics/thumbnail.webp)](https://pmndrs.github.io/examples/csg-operations-rapier-physics)</p>
  </li>
  <li>
    <p>[![faucets-select-highlight demo](https://pmndrs.github.io/examples/faucets-select-highlight/thumbnail.webp)](https://pmndrs.github.io/examples/faucets-select-highlight)</p>
  </li>
  <li>
    <p>[![rapier-physics demo](https://pmndrs.github.io/examples/rapier-physics/thumbnail.webp)](https://pmndrs.github.io/examples/rapier-physics)</p>
  </li>
  <li>
    <p>[![bloom-hdr-workflow-gltf demo](https://pmndrs.github.io/examples/bloom-hdr-workflow-gltf/thumbnail.webp)](https://pmndrs.github.io/examples/bloom-hdr-workflow-gltf)</p>
  </li>
  <li>
    <p>[![ground-projected-envmaps-lamina demo](https://pmndrs.github.io/examples/ground-projected-envmaps-lamina/thumbnail.webp)](https://pmndrs.github.io/examples/ground-projected-envmaps-lamina)</p>
  </li>
  <li>
    <p>[![basic-ballpit demo](https://pmndrs.github.io/examples/basic-ballpit/thumbnail.webp)](https://pmndrs.github.io/examples/basic-ballpit)</p>
  </li>
  <li>
    <p>[![backdrop-and-cables demo](https://pmndrs.github.io/examples/backdrop-and-cables/thumbnail.webp)](https://pmndrs.github.io/examples/backdrop-and-cables)</p>
  </li>
  <li>
    <p>[![clones demo](https://pmndrs.github.io/examples/clones/thumbnail.webp)](https://pmndrs.github.io/examples/clones)</p>
  </li>
  <li>
    <p>[![lamina-1x demo](https://pmndrs.github.io/examples/lamina-1x/thumbnail.webp)](https://pmndrs.github.io/examples/lamina-1x)</p>
  </li>
  <li>
    <p>[![react-pp-outlines demo](https://pmndrs.github.io/examples/react-pp-outlines/thumbnail.webp)](https://pmndrs.github.io/examples/react-pp-outlines)</p>
  </li>
  <li>
    <p>[![gatsby-stars demo](https://pmndrs.github.io/examples/gatsby-stars/thumbnail.webp)](https://pmndrs.github.io/examples/gatsby-stars)</p>
  </li>
  <li>
    <p>[![pmndrs-vercel demo](https://pmndrs.github.io/examples/pmndrs-vercel/thumbnail.webp)](https://pmndrs.github.io/examples/pmndrs-vercel)</p>
  </li>
  <li>
    <p>[![sport-hall demo](https://pmndrs.github.io/examples/sport-hall/thumbnail.webp)](https://pmndrs.github.io/examples/sport-hall)</p>
  </li>
  <li>
    <p>[![night-train demo](https://pmndrs.github.io/examples/night-train/thumbnail.webp)](https://pmndrs.github.io/examples/night-train)</p>
  </li>
  <li>
    <p>[![bouncy-watch demo](https://pmndrs.github.io/examples/bouncy-watch/thumbnail.webp)](https://pmndrs.github.io/examples/bouncy-watch)</p>
  </li>
  <li>
    <p>[![transparent-aesop-bottles demo](https://pmndrs.github.io/examples/transparent-aesop-bottles/thumbnail.webp)](https://pmndrs.github.io/examples/transparent-aesop-bottles)</p>
  </li>
  <li>
    <p>[![raycast-cycling demo](https://pmndrs.github.io/examples/raycast-cycling/thumbnail.webp)](https://pmndrs.github.io/examples/raycast-cycling)</p>
  </li>
  <li>
    <p>[![landing-page demo](https://pmndrs.github.io/examples/landing-page/thumbnail.webp)](https://pmndrs.github.io/examples/landing-page)</p>
  </li>
  <li>
    <p>[![scrollcontrols-gltf demo](https://pmndrs.github.io/examples/scrollcontrols-gltf/thumbnail.webp)](https://pmndrs.github.io/examples/scrollcontrols-gltf)</p>
  </li>
  <li>
    <p>[![merged-instance demo](https://pmndrs.github.io/examples/merged-instance/thumbnail.webp)](https://pmndrs.github.io/examples/merged-instance)</p>
  </li>
  <li>
    <p>[![gpgpu-curl-noise-dof demo](https://pmndrs.github.io/examples/gpgpu-curl-noise-dof/thumbnail.webp)](https://pmndrs.github.io/examples/gpgpu-curl-noise-dof)</p>
  </li>
  <li>
    <p>[![hi-key-bubbles demo](https://pmndrs.github.io/examples/hi-key-bubbles/thumbnail.webp)](https://pmndrs.github.io/examples/hi-key-bubbles)</p>
  </li>
  <li>
    <p>[![floating-instanced-shoes demo](https://pmndrs.github.io/examples/floating-instanced-shoes/thumbnail.webp)](https://pmndrs.github.io/examples/floating-instanced-shoes)</p>
  </li>
  <li>
    <p>[![simple-audio-analyser demo](https://pmndrs.github.io/examples/simple-audio-analyser/thumbnail.webp)](https://pmndrs.github.io/examples/simple-audio-analyser)</p>
  </li>
  <li>
    <p>[![camera-scroll demo](https://pmndrs.github.io/examples/camera-scroll/thumbnail.webp)](https://pmndrs.github.io/examples/camera-scroll)</p>
  </li>
  <li>
    <p>[![springy-boxes demo](https://pmndrs.github.io/examples/springy-boxes/thumbnail.webp)](https://pmndrs.github.io/examples/springy-boxes)</p>
  </li>
  <li>
    <p>[![floating-diamonds demo](https://pmndrs.github.io/examples/floating-diamonds/thumbnail.webp)](https://pmndrs.github.io/examples/floating-diamonds)</p>
  </li>
  <li>
    <p>[![gltf-animations demo](https://pmndrs.github.io/examples/gltf-animations/thumbnail.webp)](https://pmndrs.github.io/examples/gltf-animations)</p>
  </li>
  <li>
    <p>[![sparks-and-effects demo](https://pmndrs.github.io/examples/sparks-and-effects/thumbnail.webp)](https://pmndrs.github.io/examples/sparks-and-effects)</p>
  </li>
  <li>
    <p>[![camera-shake demo](https://pmndrs.github.io/examples/camera-shake/thumbnail.webp)](https://pmndrs.github.io/examples/camera-shake)</p>
  </li>
  <li>
    <p>[![ragdoll-physics demo](https://pmndrs.github.io/examples/ragdoll-physics/thumbnail.webp)](https://pmndrs.github.io/examples/ragdoll-physics)</p>
  </li>
  <li>
    <p>[![react-spring-animations demo](https://pmndrs.github.io/examples/react-spring-animations/thumbnail.webp)](https://pmndrs.github.io/examples/react-spring-animations)</p>
  </li>
  <li>
    <p>[![mount-transitions demo](https://pmndrs.github.io/examples/mount-transitions/thumbnail.webp)](https://pmndrs.github.io/examples/mount-transitions)</p>
  </li>
  <li>
    <p>[![floating-laptop demo](https://pmndrs.github.io/examples/floating-laptop/thumbnail.webp)](https://pmndrs.github.io/examples/floating-laptop)</p>
  </li>
  <li>
    <p>[![zustand-site demo](https://pmndrs.github.io/examples/zustand-site/thumbnail.webp)](https://pmndrs.github.io/examples/zustand-site)</p>
  </li>
  <li>
    <p>[![cell-fracture demo](https://pmndrs.github.io/examples/cell-fracture/thumbnail.webp)](https://pmndrs.github.io/examples/cell-fracture)</p>
  </li>
  <li>
    <p>[![router-transitions demo](https://pmndrs.github.io/examples/router-transitions/thumbnail.webp)](https://pmndrs.github.io/examples/router-transitions)</p>
  </li>
  <li>
    <p>[![soft-shadows demo](https://pmndrs.github.io/examples/soft-shadows/thumbnail.webp)](https://pmndrs.github.io/examples/soft-shadows)</p>
  </li>
  <li>
    <p>[![lulaby-city demo](https://pmndrs.github.io/examples/lulaby-city/thumbnail.webp)](https://pmndrs.github.io/examples/lulaby-city)</p>
  </li>
  <li>
    <p>[![viking-ship demo](https://pmndrs.github.io/examples/viking-ship/thumbnail.webp)](https://pmndrs.github.io/examples/viking-ship)</p>
  </li>
  <li>
    <p>[![wobbling-sphere demo](https://pmndrs.github.io/examples/wobbling-sphere/thumbnail.webp)](https://pmndrs.github.io/examples/wobbling-sphere)</p>
  </li>
  <li>
    <p>[![moksha demo](https://pmndrs.github.io/examples/moksha/thumbnail.webp)](https://pmndrs.github.io/examples/moksha)</p>
  </li>
  <li>
    <p>[![flexbox-yoga-in-webgl demo](https://pmndrs.github.io/examples/flexbox-yoga-in-webgl/thumbnail.webp)](https://pmndrs.github.io/examples/flexbox-yoga-in-webgl)</p>
  </li>
  <li>
    <p>[![confetti demo](https://pmndrs.github.io/examples/confetti/thumbnail.webp)](https://pmndrs.github.io/examples/confetti)</p>
  </li>
  <li>
    <p>[![learn-with-jason demo](https://pmndrs.github.io/examples/learn-with-jason/thumbnail.webp)](https://pmndrs.github.io/examples/learn-with-jason)</p>
  </li>
  <li>
    <p>[![volumetric-spotlight demo](https://pmndrs.github.io/examples/volumetric-spotlight/thumbnail.webp)](https://pmndrs.github.io/examples/volumetric-spotlight)</p>
  </li>
</Grid>

## Game prototypes

<Grid>
  <li>
    <p>[![racing-game demo](https://pmndrs.github.io/examples/racing-game/thumbnail.webp)](https://pmndrs.github.io/examples/racing-game)</p>
  </li>
  <li>
    <p>[![pinball-in-70-lines demo](https://pmndrs.github.io/examples/pinball-in-70-lines/thumbnail.webp)](https://pmndrs.github.io/examples/pinball-in-70-lines)</p>
  </li>
  <li>
    <p>[![space-game demo](https://pmndrs.github.io/examples/space-game/thumbnail.webp)](https://pmndrs.github.io/examples/space-game)</p>
  </li>
  <li>
    <p>[![minecraft demo](https://pmndrs.github.io/examples/minecraft/thumbnail.webp)](https://pmndrs.github.io/examples/minecraft)</p>
  </li>
  <li>
    <p>[![arkanoid demo](https://pmndrs.github.io/examples/arkanoid/thumbnail.webp)](https://pmndrs.github.io/examples/arkanoid)</p>
  </li>
  <li>
    <p>[![rapier-ping-pong demo](https://pmndrs.github.io/examples/rapier-ping-pong/thumbnail.webp)](https://pmndrs.github.io/examples/rapier-ping-pong)</p>
  </li>
  <li>
    <p>[![arkanoid-under-60-loc demo](https://pmndrs.github.io/examples/arkanoid-under-60-loc/thumbnail.webp)](https://pmndrs.github.io/examples/arkanoid-under-60-loc)</p>
  </li>
</Grid>

## Basic examples

<Grid>
  <li>
    <p>[![basic-demo demo](https://pmndrs.github.io/examples/basic-demo/thumbnail.webp)](https://pmndrs.github.io/examples/basic-demo)</p>
  </li>
  <li>
    <Codesandbox id="yup2o" />
  </li>
  <li>
    <p>[![drei-rendertexture demo](https://pmndrs.github.io/examples/drei-rendertexture/thumbnail.webp)](https://pmndrs.github.io/examples/drei-rendertexture)</p>
  </li>
  <li>
    <p>[![bvh demo](https://pmndrs.github.io/examples/bvh/thumbnail.webp)](https://pmndrs.github.io/examples/bvh)</p>
  </li>
  <li>
    <p>[![environment-blur-and-transitions demo](https://pmndrs.github.io/examples/environment-blur-and-transitions/thumbnail.webp)](https://pmndrs.github.io/examples/environment-blur-and-transitions)</p>
  </li>
  <li>
    <p>[![pairing-threejs-to-ui demo](https://pmndrs.github.io/examples/pairing-threejs-to-ui/thumbnail.webp)](https://pmndrs.github.io/examples/pairing-threejs-to-ui)</p>
  </li>
  <li>
    <p>[![inverted-stencil-buffer demo](https://pmndrs.github.io/examples/inverted-stencil-buffer/thumbnail.webp)](https://pmndrs.github.io/examples/inverted-stencil-buffer)</p>
  </li>
  <li>
    <p>[![stencil-mask demo](https://pmndrs.github.io/examples/stencil-mask/thumbnail.webp)](https://pmndrs.github.io/examples/stencil-mask)</p>
  </li>
  <li>
    <p>[![transformcontrols-and-makedefault demo](https://pmndrs.github.io/examples/transformcontrols-and-makedefault/thumbnail.webp)](https://pmndrs.github.io/examples/transformcontrols-and-makedefault)</p>
  </li>
  <li>
    <p>[![bounds-and-makedefault demo](https://pmndrs.github.io/examples/bounds-and-makedefault/thumbnail.webp)](https://pmndrs.github.io/examples/bounds-and-makedefault)</p>
  </li>
  <li>
    <p>[![instanced-vertex-colors demo](https://pmndrs.github.io/examples/instanced-vertex-colors/thumbnail.webp)](https://pmndrs.github.io/examples/instanced-vertex-colors)</p>
  </li>
  <li>
    <p>[![progressive-loading-states-with-suspense demo](https://pmndrs.github.io/examples/progressive-loading-states-with-suspense/thumbnail.webp)](https://pmndrs.github.io/examples/progressive-loading-states-with-suspense)</p>
  </li>
  <li>
    <p>[![view-tracking demo](https://pmndrs.github.io/examples/view-tracking/thumbnail.webp)](https://pmndrs.github.io/examples/view-tracking) -- <span>views</span>, <span>portals</span></p>
  </li>
  <li>
    <p>[![multiple-views-with-uniform-controls demo](https://pmndrs.github.io/examples/multiple-views-with-uniform-controls/thumbnail.webp)](https://pmndrs.github.io/examples/multiple-views-with-uniform-controls) -- <span>views</span>, <span>portals</span></p>
  </li>
  <li>
    <p>[![canvas-text demo](https://pmndrs.github.io/examples/canvas-text/thumbnail.webp)](https://pmndrs.github.io/examples/canvas-text) -- <span>html</span>, <span>scroll</span></p>
  </li>
  <li>
    <p>[![gltf-animations-re-used demo](https://pmndrs.github.io/examples/gltf-animations-re-used/thumbnail.webp)](https://pmndrs.github.io/examples/gltf-animations-re-used)</p>
  </li>
  <li>
    <p>[![re-using-gltfs demo](https://pmndrs.github.io/examples/re-using-gltfs/thumbnail.webp)](https://pmndrs.github.io/examples/re-using-gltfs)</p>
  </li>
  <li>
    <p>[![svg-renderer demo](https://pmndrs.github.io/examples/svg-renderer/thumbnail.webp)](https://pmndrs.github.io/examples/svg-renderer)</p>
  </li>
  <li>
    <p>[![mixing-html-and-webgl demo](https://pmndrs.github.io/examples/mixing-html-and-webgl/thumbnail.webp)](https://pmndrs.github.io/examples/mixing-html-and-webgl)</p>
  </li>
  <li>
    <p>[![viewcube demo](https://pmndrs.github.io/examples/viewcube/thumbnail.webp)](https://pmndrs.github.io/examples/viewcube)</p>
  </li>
  <li>
    <p>[![mixing-controls demo](https://pmndrs.github.io/examples/mixing-controls/thumbnail.webp)](https://pmndrs.github.io/examples/mixing-controls)</p>
  </li>
  <li>
    <p>[![video-textures demo](https://pmndrs.github.io/examples/video-textures/thumbnail.webp)](https://pmndrs.github.io/examples/video-textures)</p>
  </li>
  <li>
    <p>[![sky-dome-with-annotations demo](https://pmndrs.github.io/examples/sky-dome-with-annotations/thumbnail.webp)](https://pmndrs.github.io/examples/sky-dome-with-annotations)</p>
  </li>
  <li>
    <p>[![tying-canvas-to-scroll-offset demo](https://pmndrs.github.io/examples/tying-canvas-to-scroll-offset/thumbnail.webp)](https://pmndrs.github.io/examples/tying-canvas-to-scroll-offset)</p>
  </li>
  <li>
    <p>[![edgesgeometry demo](https://pmndrs.github.io/examples/edgesgeometry/thumbnail.webp)](https://pmndrs.github.io/examples/edgesgeometry)</p>
  </li>
  <li>
    <p>[![html-annotations demo](https://pmndrs.github.io/examples/html-annotations/thumbnail.webp)](https://pmndrs.github.io/examples/html-annotations)</p>
  </li>
  <li>
    <p>[![shadermaterials demo](https://pmndrs.github.io/examples/shadermaterials/thumbnail.webp)](https://pmndrs.github.io/examples/shadermaterials)</p>
  </li>
  <li>
    <p>[![simple-physics-demo demo](https://pmndrs.github.io/examples/simple-physics-demo/thumbnail.webp)](https://pmndrs.github.io/examples/simple-physics-demo)</p>
  </li>
  <li>
    <p>[![trigger-meshes demo](https://pmndrs.github.io/examples/trigger-meshes/thumbnail.webp)](https://pmndrs.github.io/examples/trigger-meshes)</p>
  </li>
  <li>
    <p>[![simple-physics-demo-with-debug-bounds demo](https://pmndrs.github.io/examples/simple-physics-demo-with-debug-bounds/thumbnail.webp)](https://pmndrs.github.io/examples/simple-physics-demo-with-debug-bounds)</p>
  </li>
  <li>
    <p>[![selective-outlines demo](https://pmndrs.github.io/examples/selective-outlines/thumbnail.webp)](https://pmndrs.github.io/examples/selective-outlines)</p>
  </li>
  <li>
    <p>[![instances demo](https://pmndrs.github.io/examples/instances/thumbnail.webp)](https://pmndrs.github.io/examples/instances)</p>
  </li>
  <li>
    <p>[![physics-with-convex-polyhedrons demo](https://pmndrs.github.io/examples/physics-with-convex-polyhedrons/thumbnail.webp)](https://pmndrs.github.io/examples/physics-with-convex-polyhedrons)</p>
  </li>
  <li>
    <p>[![color-grading demo](https://pmndrs.github.io/examples/color-grading/thumbnail.webp)](https://pmndrs.github.io/examples/color-grading)</p>
  </li>
  <li>
    <p>[![grass-shader demo](https://pmndrs.github.io/examples/grass-shader/thumbnail.webp)](https://pmndrs.github.io/examples/grass-shader)</p>
  </li>
  <li>
    <p>[![clouds demo](https://pmndrs.github.io/examples/clouds/thumbnail.webp)](https://pmndrs.github.io/examples/clouds)</p>
  </li>
  <li>
    <p>[![svg-maps-with-html-annotations demo](https://pmndrs.github.io/examples/svg-maps-with-html-annotations/thumbnail.webp)](https://pmndrs.github.io/examples/svg-maps-with-html-annotations)</p>
  </li>
  <li>
    <p>[![re-using-geometry-and-level-of-detail demo](https://pmndrs.github.io/examples/re-using-geometry-and-level-of-detail/thumbnail.webp)](https://pmndrs.github.io/examples/re-using-geometry-and-level-of-detail)</p>
  </li>
  <li>
    <p>[![html-markers demo](https://pmndrs.github.io/examples/html-markers/thumbnail.webp)](https://pmndrs.github.io/examples/html-markers)</p>
  </li>
  <li>
    <p>[![bezier-curves-and-nodes demo](https://pmndrs.github.io/examples/bezier-curves-and-nodes/thumbnail.webp)](https://pmndrs.github.io/examples/bezier-curves-and-nodes)</p>
  </li>
  <li>
    <p>[![shader-fire demo](https://pmndrs.github.io/examples/shader-fire/thumbnail.webp)](https://pmndrs.github.io/examples/shader-fire)</p>
  </li>
  <li>
    <p>[![water-shader demo](https://pmndrs.github.io/examples/water-shader/thumbnail.webp)](https://pmndrs.github.io/examples/water-shader)</p>
  </li>
  <li>
    <p>[![staging-and-camerashake demo](https://pmndrs.github.io/examples/staging-and-camerashake/thumbnail.webp)](https://pmndrs.github.io/examples/staging-and-camerashake)</p>
  </li>
  <li>
    <p>[![shader-hmr demo](https://pmndrs.github.io/examples/shader-hmr/thumbnail.webp)](https://pmndrs.github.io/examples/shader-hmr)</p>
  </li>
</Grid>
]]></page>
<page path="/api/canvas" title="Canvas"><![CDATA[URL: https://r3f.docs.pmnd.rs/api/canvas
Description: The Canvas object is your portal into three.js


The `Canvas` object is where you start to define your React Three Fiber Scene.

```jsx
import React from 'react'
import { Canvas } from '@react-three/fiber'

const App = () => (
  <Canvas>
    <pointLight position={[10, 10, 10]} />
    <mesh>
      <sphereGeometry />
      <meshStandardMaterial color="hotpink" />
    </mesh>
  </Canvas>
)
```

## Properties

| Prop            | Description                                                                                                                                       | Default                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| children        | three.js JSX elements or regular components                                                                                                       |                                                            |
| fallback        | optional DOM JSX elements or regular components in case GL is not supported                                                                       |                                                            |
| gl              | Props that go into the default renderer. Accepts sync/async callback with default props `gl={defaults => new Renderer({ ...defaults })}`          | `{}`                                                       |
| camera          | Props that go into the default camera, or your own `THREE.Camera`                                                                                 | `{ fov: 75, near: 0.1, far: 1000, position: [0, 0, 5] }`   |
| scene           | Props that go into the default scene, or your own `THREE.Scene`                                                                                   | `{}`                                                       |
| shadows         | Props that go into `gl.shadowMap`, can be set true for `PCFsoft` or one of the following: 'basic', 'percentage', 'soft', 'variance'               | `false`                                                    |
| raycaster       | Props that go into the default raycaster                                                                                                          | `{}`                                                       |
| frameloop       | Render mode: always, demand, never                                                                                                                | `always`                                                   |
| resize          | Resize config, see react-use-measure's options                                                                                                    | `{ scroll: true, debounce: { scroll: 50, resize: 0 } }`    |
| orthographic    | Creates an orthographic camera                                                                                                                    | `false`                                                    |
| dpr             | Pixel-ratio, use `window.devicePixelRatio`, or automatic: [min, max]                                                                              | `[1, 2]`                                                   |
| legacy          | Enables THREE.ColorManagement in three r139 or later                                                                                              | `false`                                                    |
| linear          | Switch off automatic sRGB color space and gamma correction                                                                                        | `false`                                                    |
| events          | Configuration for the event manager, as a function of state                                                                                       | `import { events } from "@react-three/fiber"`              |
| eventSource     | The source where events are being subscribed to, HTMLElement                                                                                      | `React.RefObject<HTMLElement>`, `gl.domElement.parentNode` |
| eventPrefix     | The event prefix that is cast into canvas pointer x/y events                                                                                      | `offset`                                                   |
| flat            | Use `THREE.NoToneMapping` instead of `THREE.ACESFilmicToneMapping`                                                                                | `false`                                                    |
| onCreated       | Callback after the canvas has rendered (but not yet committed)                                                                                    | `(state) => {}`                                            |
| onPointerMissed | Response for pointer clicks that have missed any target                                                                                           | `(event) => {}`                                            |

## Defaults

Canvas uses [createRoot](#createroot) which will create a translucent `THREE.WebGLRenderer` with the following constructor args:

- antialias=true
- alpha=true
- powerPreference="high-performance"

and with the following properties:

- outputColorSpace = THREE.SRGBColorSpace
- toneMapping = THREE.ACESFilmicToneMapping

It will also create the following scene internals:

- A `THREE.Perspective` camera
- A `THREE.Orthographic` cam if `orthographic` is true
- A `THREE.PCFSoftShadowMap` if `shadows` is true
- A `THREE.Scene` (into which all the JSX is rendered) and a `THREE.Raycaster`

In recent versions of threejs, `THREE.ColorManagement.enabled` will be set to `true` to enable automatic conversion of colors according to the renderer's configured color space. R3F will handle texture color space conversion. For more on this topic, see [https://threejs.org/docs/#manual/en/introduction/Color-management](https://threejs.org/docs/#manual/en/introduction/Color-management).

## Errors and fallbacks

On some systems WebGL may not be supported, you can provide a fallback component that will be rendered instead of the canvas:

```jsx
<Canvas fallback={<div>Sorry no WebGL supported!</div>}>
  <mesh />
</Canvas>
```

You should also safeguard the canvas against WebGL context crashes, for instance if users have the GPU disabled or GPU drivers are faulty.

```jsx
import { useErrorBoundary } from 'use-error-boundary'

function App() {
  const { ErrorBoundary, didCatch, error } = useErrorBoundary()
  return didCatch ? (
    <div>{error.message}</div>
  ) : (
    <ErrorBoundary>
      <Canvas>
        <mesh />
      </Canvas>
    </ErrorBoundary>
  )
}
```

> [!NOTE]
> Ideally, and if possible, your fallback is a seamless, visual replacement for what the canvas would have otherwise rendered.

## WebGPU

Recent Three.js now includes a WebGPU renderer. While still a work in progress and not fully backward-compatible with all of Three's features, the renderer requires an async initialization method. R3F streamlines this by allowing the gl prop to return a promise.

```tsx
import * as THREE from 'three/webgpu'
import * as TSL from 'three/tsl'
import { Canvas, extend, useFrame, useThree } from '@react-three/fiber'

declare module '@react-three/fiber' {
  interface ThreeElements extends ThreeToJSXElements<typeof THREE> {}
}

extend(THREE as any)

export default () => (
  <Canvas
    gl={async (props) => {
      const renderer = new THREE.WebGPURenderer(props as any)
      await renderer.init()
      return renderer
    }}>
      <mesh>
        <meshBasicNodeMaterial />
        <boxGeometry />
      </mesh>
  </Canvas>
)
```

## Custom Canvas

R3F can render to a root, similar to how `react-dom` and all the other React renderers work. This allows you to shave off `react-dom` (~40kb), `react-use-measure` (~3kb) and, if you don't need them, `pointer-events` (~7kb) (you need to explicitly import `events` and add them to the config otherwise).

Roots have the same options and properties as `Canvas`, but you are responsible for resizing it. It requires an existing DOM `<canvas>` object into which it renders.

### CreateRoot

Creates a root targeting a canvas, rendering JSX.

```jsx
import * as THREE from 'three'
import { extend, createRoot, events } from '@react-three/fiber'

// Register the THREE namespace as native JSX elements.
// See below for notes on tree-shaking
extend(THREE)

// Create a react root
const root = createRoot(document.querySelector('canvas'))

async function app() {
  // Configure the root, inject events optionally, set camera, etc
  // This *must* be called before render, and it must be awaited
  await root.configure({ events, camera: { position: [0, 0, 50] } })

  // createRoot by design is not responsive, you have to take care of resize yourself
  window.addEventListener('resize', () => {
    root.configure({ size: { width: window.innerWidth, height: window.innerHeight } })
  })

  // Trigger resize
  window.dispatchEvent(new Event('resize'))

  // Render entry point
  root.render(<App />)

  // Unmount and dispose of memory
  // root.unmount()
}

app()
```

## Tree-shaking

New with v8, the underlying reconciler no longer pulls in the THREE namespace automatically.

This enables a granular catalogue which also enables tree-shaking via the `extend` API:

```jsx
import { extend, createRoot } from '@react-three/fiber'
import { Mesh, BoxGeometry, MeshStandardMaterial } from 'three'

extend({ Mesh, BoxGeometry, MeshStandardMaterial })

createRoot(canvas).render(
  <>
    <mesh>
      <boxGeometry />
      <meshStandardMaterial />
    </mesh>
  </>,
)
```

There's an [official babel plugin](https://github.com/pmndrs/react-three-babel) which will do this for you automatically:

```jsx
// In:

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

createRoot(canvasNode).render(
  <mesh>
    <boxGeometry />
    <meshStandardMaterial />
  </mesh>,
)

// Out:

import { createRoot, extend } from '@react-three/fiber'
import { Mesh as _Mesh, BoxGeometry as _BoxGeometry, MeshStandardMaterial as _MeshStandardMaterial } from 'three'

extend({
  Mesh: _Mesh,
  BoxGeometry: _BoxGeometry,
  MeshStandardMaterial: _MeshStandardMaterial,
})

createRoot(canvasNode).render(
  <mesh>
    <boxGeometry />
    <meshStandardMaterial />
  </mesh>,
)
```
]]></page>
<page path="/getting-started/community-r3f-components" title="Community R3F Components"><![CDATA[URL: https://r3f.docs.pmnd.rs/getting-started/community-r3f-components
Description: This page showcases some React Three Fiber/r3f community components that have not been merged to the drei components collection or to another pmndrs project.


If you'd like to list new community components, please make a PR to [this doc](https://github.com/pmndrs/react-three-fiber/tree/master/docs/getting-started/community-r3f-components.mdx) file. It showcases some r3f community components that have not been merged to the [drei](http://drei.docs.pmnd.rs) components collection or to another [pmndrs](https://github.com/pmndrs) project.

## R3F community components 

### Repos and docs

This page showcases some React Three Fiber/r3f community components that have not been merged to the [drei](http://drei.docs.pmnd.rs) components collection or to another [pmndrs](https://github.com/pmndrs) project. If you'd like to list new community components, please make a PR to [this doc](https://github.com/pmndrs/react-three-fiber/tree/master/docs/getting-started/community-r3f-components.mdx) file. 

#### Data sources

 - [NASA-AMMOS/3DTilesRendererJS](https://github.com/NASA-AMMOS/3DTilesRendererJS/) (r3f [readme](https://github.com/NASA-AMMOS/3DTilesRendererJS/blob/master/src/r3f/README.md)) repo with doc
 - Luma Labs [Gaussian Splats](https://cdn-luma.com/public/lumalabs.ai/luma-web-library/0.2/fefe154/index.html#react-three-fiber) renderer doc with demos
 - [NYTimes/three-loader-3dtiles](https://nytimes.github.io/three-loader-3dtiles) 

#### Renderers & frameworks

 - Takram three-geospatial [clouds doc](https://github.com/takram-design-engineering/three-geospatial/tree/main/packages/clouds) and [demos](https://takram-design-engineering.github.io/three-geospatial/?path=/story/clouds-3d-tiles-renderer-integration--tokyo), and [atmosphere doc](https://github.com/takram-design-engineering/three-geospatial/tree/main/packages/atmosphere)
 - [Looking Glass](https://docs.lookingglassfactory.com/developer-tools/webxr/react-three-fiber) doc and demos
 - [Theatre-js](https://github.com/theatre-js/theatre) repo and [doc](https://www.theatrejs.com/docs/latest)

#### Materials

 - [FarazzShaikh/CustomShaderMaterial](https://github.com/FarazzShaikh/THREE-CustomShaderMaterial)
 - [pmndrs/THREE.MeshLine](https://github.com/pmndrs/meshline)
 - [ektogamat/R3F-Ultimate-Lens-Flare](https://github.com/ektogamat/R3F-Ultimate-Lens-Flare)
 - [troika-three-text](https://github.com/protectwise/troika/tree/main/packages/troika-three-text)

#### Utilities

 - [utsuboco/r3f-perf](https://github.com/utsuboco/r3f-perf)


### Codesandboxes and demos

<Grid cols={3}>
  <li>
    [NASA-AMMOS/3DTilesRendererJS](https://github.com/NASA-AMMOS/3DTilesRendererJS)

    [<Img src="https://raw.githubusercontent.com/NASA-AMMOS/3DTilesRendererJS/master/images/header-mars.png" alt="3DTilesRendererJS r3f demo" className="aspect-[16/9] object-cover"  width="1763" height="926" />](https://nasa-ammos.github.io/3DTilesRendererJS/example/bundle/r3f/basic.html)
  </li>
  <li>
    [Takram three-geospatial clouds](https://github.com/takram-design-engineering/three-geospatial/tree/main/packages/clouds)

    [<Img src="https://github.com/takram-design-engineering/three-geospatial/raw/main/packages/clouds/docs/london.jpg" alt="Takram three-geospatial clouds" className="aspect-[16/9] object-cover"  width="1763" height="926" />](https://takram-design-engineering.github.io/three-geospatial/?path=/story/clouds-3d-tiles-renderer-integration--tokyo)
  </li>
  <li>
    [Luma Gaussian Splats](https://cdn-luma.com/public/lumalabs.ai/luma-web-library/0.2/fefe154/index.html#react-three-fiber)
    <Codesandbox id="h2fkgq" />
  </li>
  <li>
    [NYTimes/three-loader-3dtiles](https://github.com/nytimes/three-loader-3dtiles/blob/dev/examples/r3f/src/index.tsx)

    [<Img src="https://rd.nytimes.com/static/1ffcbe7f02d6168aecebdb7a84929dcf/1b9fc/7579e21f-3af0-46bb-a073-28c4a97594f9_Demo4.jpg" alt="three-loader-3dtiles r3f demo" className="aspect-[16/9] object-cover"  width="1763" height="926" />](https://nytimes.github.io/three-loader-3dtiles/dist/web/examples/demos/realitycapture/)
  </li>
  <li>
    [Looking Glass](https://docs.lookingglassfactory.com/developer-tools/webxr/react-three-fiber)
    <Codesandbox id="xzlmzz" screenshot_url="https://blog.lookingglassfactory.com/content/images/size/w2000/2024/05/LKG-32-Spatial-Display-Portrait-Cleopatra-1.jpg"/> 
  </li> 
  <li>
    [Theatre-js](https://github.com/theatre-js/theatre)
    <Codesandbox id="6xfrsv" screenshot_url="https://www.theatrejs.com/images/docs/0.5/manual/studio/ui.png" />
  </li>
  <li>
    [Farazz/CustomShaderMaterial](https://github.com/FarazzShaikh/THREE-CustomShaderMaterial)

    [<Img src="https://raw.githubusercontent.com/FarazzShaikh/THREE-CustomShaderMaterial/main/assets/waves-demo.png" alt="THREE-CustomShaderMaterial r3f demo" className="aspect-[16/9] object-cover"  width="1763" height="926" />](https://farazzshaikh.github.io/THREE-CustomShaderMaterial/#/caustics)
  </li>
  <li>
    [Takram three-geospatial atmosphere](https://github.com/takram-design-engineering/three-geospatial/tree/main/packages/atmosphere)

    [<Img src="https://media.githubusercontent.com/media/takram-design-engineering/three-geospatial/main/packages/atmosphere/docs/manhattan.jpg" alt="Takram three-geospatial atmosphere" className="aspect-[16/9] object-cover"  width="1763" height="926" />](https://takram-design-engineering.github.io/three-geospatial/?path=/story/atmosphere-3d-tiles-renderer-integration--manhattan)
  </li>
  <li>
    [utsuboco/r3f-perf](https://github.com/utsuboco/r3f-perf)
    <Codesandbox id="ykfpwf" />
  </li>
  <li>
    [pmndrs/THREE.MeshLine](https://github.com/pmndrs/meshline)
    <Codesandbox id="vl221" />
  </li>
  <li>
    [ektogamat/R3F-Ultimate-Lens-Flare](https://github.com/ektogamat/R3F-Ultimate-Lens-Flare)

    [<Img src="https://raw.githubusercontent.com/ektogamat/R3F-Ultimate-Lens-Flare/main/thumbnail.png" alt="R3F-Ultimate-Lens-Flare demo" className="aspect-[16/9] object-cover"  width="1763" height="926" />](https://ultimate-lens-flare.vercel.app/)
  </li>
</Grid>
]]></page>
<page path="/api/objects" title="Objects, properties and constructor arguments"><![CDATA[URL: https://r3f.docs.pmnd.rs/api/objects
Description: All the effective ways of using React Three Fiber


## Declaring objects

You can use [three.js's entire object catalogue and all properties](https://threejs.org/docs). When in doubt, always consult the docs.

❌ You could lay out an object like this:

```jsx
<mesh
  visible
  userData={{ hello: 'world' }}
  position={new THREE.Vector3(1, 2, 3)}
  rotation={new THREE.Euler(Math.PI / 2, 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.

```jsx
<mesh visible userData={{ hello: 'world' }} position={[1, 2, 3]} rotation={[Math.PI / 2, 0, 0]}>
  <sphereGeometry args={[1, 16, 16]} />
  <meshStandardMaterial color="hotpink" transparent />
</mesh>
```

## Constructor arguments

In three.js objects are classes that are instantiated. These classes can receive one-time constructor arguments (`new THREE.SphereGeometry(1, 32)`), and properties (`someObject.visible = true`). In React Three Fiber, constructor arguments are always passed as an array via `args`. If args change later on, the object must naturally get reconstructed from scratch!

```jsx
<sphereGeometry args={[1, 32]} />
```

## Shortcuts

### Set

All properties whose underlying object has a `.set()` method can directly receive the same arguments that `set` would otherwise take. For example [`THREE.Color.set`](https://threejs.org/docs/#api/en/math/Color.set) can take a color string, so instead of `color={new THREE.Color('hotpink')}` you can simply write `color="hotpink"`. Some `set` methods take multiple arguments, for instance [`THREE.Vector3`](https://threejs.org/docs/#api/en/math/Vector3.set), give it an array in that case `position={[100, 0, 0]}`.

```jsx
<mesh position={[1, 2, 3]} />
  <meshStandardMaterial color="hotpink" />
```

> [!NOTE]
> If you do link up an existing object to a property, for instance a THREE.Vector3() to a position, be aware that this will end up copying the object in most cases as it calls .copy() on the target. This only applies to objects that expose both .set() and .copy() (Vectors, Eulers, Matrix, ...). If you link up an existing material or geometry on the other hand, it will overwrite, because more these objects do not have a .set() method.

### SetScalar

Properties that have a `setScalar` method (for instance `Vector3`) can be set like so:

```jsx
// Translates to <mesh scale={[1, 1, 1]} />
<mesh scale={1} />
```

## Piercing into nested properties

If you want to reach into nested attributes (for instance: `mesh.rotation.x`), just use dash-case.

```jsx
<mesh rotation-x={1} material-uniforms-resolution-value={[512, 512]} />
```

## Dealing with non-scene objects

You can put non-Object3D primitives (geometries, materials, etc) into the render tree as well. They take the same properties and constructor arguments they normally would.

You might be wondering why you would want to put something in the "scene" that normally would not be part of it, in a vanilla three.js app at least. For the same reason you declare any object: it becomes managed, reactive and auto-disposes. These objects are not technically part of the scene, but they "attach" to a parent which is.

### Attach

Use `attach` to bind objects to their parent. If you unmount the attached object it will be taken off its parent automatically.

The following attaches a material to the `material` property of a mesh and a geometry to the `geometry` property:

```jsx
<mesh>
  <meshBasicMaterial attach="material" />
  <boxGeometry attach="geometry" />
```

> [!NOTE]
> All objects extending `THREE.Material` receive `attach="material"`, and all objects extending `THREE.BufferGeometry` receive `attach="geometry"`. You do not have to type it out!

```jsx
<mesh>
  <meshBasicMaterial />
  <boxGeometry />
```

You can also deeply nest attach through piercing. The following adds a buffer-attribute to `geometry.attributes.position` and then adds the buffer geometry to `mesh.geometry`.

```jsx
<mesh>
  <bufferGeometry>
    <bufferAttribute attach="attributes-position" args={[v, 3]} />
```

#### More examples

```jsx
// Attach bar to foo.a
<foo>
  <bar attach="a" />

// Attach bar to foo.a.b and foo.a.b.c (nested object attach)
<foo>
  <bar attach="a-b" />
  <bar attach="a-b-c" />

// Attach bar to foo.a[0] and foo.a[1] (array attach is just object attach)
<foo>
  <bar attach="a-0" />
  <bar attach="a-1" />

// Attach bar to foo via explicit add/remove functions
<foo>
  <bar attach={(parent, self) => {
    parent.add(self)
    return () => parent.remove(self)
  }} />

// The same as a one liner
<foo>
  <bar attach={(parent, self) => (parent.add(self), () => parent.remove(self))} />
```

#### Real-world use-cases:

Attaching to nested objects, for instance a shadow-camera:

```diff
- <directionalLight
-   castShadow
-   position={[2.5, 8, 5]}
-   shadow-mapSize={[1024, 1024]}
-   shadow-camera-far={50}
-   shadow-camera-left={-10}
-   shadow-camera-right={10}
-   shadow-camera-top={10}
-   shadow-camera-bottom={-10}
- />
+ <directionalLight castShadow position={[2.5, 8, 5]} shadow-mapSize={[1024, 1024]}>
+   <orthographicCamera attach="shadow-camera" args={[-10, 10, 10, -10]} />
+ </directionalLight>
```

Arrays must have explicit order, for instance multi-materials:

```jsx
<mesh>
  {colors.map((color, index) => <meshBasicMaterial key={index} attach={`material-${index}`} color={color} />}
</mesh>
```

## Putting already existing objects into the scene-graph

You can use the `primitive` placeholder for that. You can still give it properties or attach nodes to it. Never add the same object multiple times, this is not allowed in three.js! Primitives will not dispose of the object they carry on unmount, you are responsible for disposing of it!

```jsx
const mesh = new THREE.Mesh(geometry, material)

function Component() {
  return <primitive object={mesh} position={[10, 0, 0]} />
```

> [!NOTE]
> Scene objects can only ever be added once in Threejs. If you attempt to add one and the same object in two places Threejs will remove the first instance automatically. This will also happen with primitive! If you want to re-use an existing object, you must clone it first.

## Using 3rd-party objects declaratively

The `extend` function extends React Three Fiber's catalogue of JSX elements. Components added this way can then be referenced in the scene-graph using camel casing similar to other primitives.

```jsx
import { extend } from '@react-three/fiber'
import { OrbitControls, TransformControls } from 'three-stdlib'
extend({ OrbitControls, TransformControls })

// ...
return (
  <>
    <orbitControls />
    <transformControls />
```

If you're using TypeScript, you'll also need to [extend the JSX namespace](/tutorials/v9-migration-guide#threeelements).

## Disposal

Freeing resources is a [manual chore in `three.js`](https://threejs.org/docs/#manual/en/introduction/How-to-dispose-of-objects), but React is aware of object-lifecycles, hence React 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 switch it off by placing `dispose={null}` onto meshes, materials, etc, or even on parent containers like groups, it is now valid for the entire tree.

```jsx
const globalGeometry = new THREE.BoxGeometry()
const globalMaterial = new THREE.MeshBasicMaterial()

function Mesh() {
  return (
    <group dispose={null}>
      <mesh geometry={globalGeometry} material={globalMaterial} />
```

## Shader material uniforms

`ShaderMaterial`, `RawShaderMaterial` and subclasses keep the material's [`uniforms` object](https://threejs.org/docs/#ShaderMaterial.uniforms) stable. When you pass a new `uniforms` object, React Three Fiber merges the incoming uniforms into the existing target instead of replacing it.

This preserves three.js internal uniform caching, even if your component creates a fresh `uniforms` object on each render. Existing uniform entries are updated in place and new entries are added as needed.

```jsx
<shaderMaterial
  uniforms={{
    time: { value: time },
    color: { value: color },
  }}
/>
```

To get a stable reference to the material's `uniforms`, use the React ref.

```jsx
function Component() {
  const ref = useRef()

  // This object is merged into the material, so mutating this reference
  // later will not update the shader.
  const uniforms = useMemo(
    () => ({
      time: { value: 0 },
      color: { value: color },
    }),
    [color],
  )

  useFrame(({ clock }) => {
    // The material ref's uniforms object is stable and should be mutated instead.
    ref.current.uniforms.time.value = clock.elapsedTime
  })

  return (
    <mesh>
      <shaderMaterial ref={ref} uniforms={uniforms} />
    </mesh>
  )
}
```
]]></page>
<page path="/api/hooks" title="Hooks"><![CDATA[URL: https://r3f.docs.pmnd.rs/api/hooks
Description: Hooks are the heart of react-three-fiber


Hooks allow you to tie or request specific information to your component. For instance, components that want to participate in the renderloop can use `useFrame`, components that need to be informed of three.js specifics can use `useThree` and so on. All hooks clean up after themselves once the component unmounts.

> [!NOTE]
> Hooks can only be used inside the Canvas element because they rely on context!

❌ You cannot expect something like this to work:

```jsx
import { useThree } from '@react-three/fiber'

function App() {
  const { size } = useThree() // This will just crash
  return (
    <Canvas>
      <mesh>
```

✅ Do this instead:

```jsx
function Foo() {
  const { size } = useThree()
  ...
}

function App() {
  return (
    <Canvas>
      <Foo />
```

## `useThree`

This hook gives you access to the state model which contains the default renderer, the scene, your camera, and so on. It also gives you the current size of the canvas in screen and viewport coordinates.

```jsx
import { useThree } from '@react-three/fiber'

function Foo() {
  const state = useThree()
```

The hook is reactive, if you resize the browser for instance, you get fresh measurements, same applies to any of the state objects that may change.

### `state` properties

| Prop              | Description                                                                   | Type                                                                                                                                                                                                           |
| ----------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gl`              | Renderer                                                                      | `THREE.WebGLRenderer`                                                                                                                                                                                          |
| `scene`           | Scene                                                                         | `THREE.Scene`                                                                                                                                                                                                  |
| `camera`          | Camera                                                                        | `THREE.PerspectiveCamera`                                                                                                                                                                                      |
| `raycaster`       | Default raycaster                                                             | `THREE.Raycaster`                                                                                                                                                                                              |
| `pointer`         | Contains updated, normalized, centric pointer coordinates                     | `THREE.Vector2`                                                                                                                                                                                                |
| `mouse`           | Note: this is deprecated, use `pointer` instead! Normalized event coordinates | `THREE.Vector2`                                                                                                                                                                                                |
| `clock`           | Running system clock                                                          | `THREE.Clock`                                                                                                                                                                                                  |
| `linear`          | True when the colorspace is linear                                            | `boolean`                                                                                                                                                                                                      |
| `flat`            | True when no tonemapping is used                                              | `boolean`                                                                                                                                                                                                      |
| `legacy`          | Disables global color management via `THREE.ColorManagement`                  | `boolean`                                                                                                                                                                                                      |
| `frameloop`       | Render mode: always, demand, never                                            | `always`, `demand`, `never`                                                                                                                                                                                    |
| `performance`     | System regression                                                             | `{ current: number, min: number, max: number, debounce: number, regress: () => void }`                                                                                                                         |
| `size`            | Canvas size in pixels                                                         | `{ width: number, height: number, top: number, left: number }`                                                                                                                                                 |
| `viewport`        | Canvas viewport size in three.js units. Note: This is different from [`gl.getViewport`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer.getViewport) which returns the drawbuffer size                                               | `{ width: number, height: number, initialDpr: number, dpr: number, factor: number, distance: number, aspect: number, getCurrentViewport: (camera?: Camera, target?: THREE.Vector3, size?: Size) => Viewport }` |
| `xr`              | XR interface, manages WebXR rendering                                         | `{ connect: () => void, disconnect: () => void }`                                                                                                                                                              |
| `set`             | Allows you to set any state property                                          | `(state: SetState<RootState>) => void`                                                                                                                                                                         |
| `get`             | Allows you to retrieve any state property non-reactively                      | `() => GetState<RootState>`                                                                                                                                                                                    |
| `invalidate`      | Request a new render, given that `frameloop === 'demand'`                     | `() => void`                                                                                                                                                                                                   |
| `advance`         | Advance one tick, given that `frameloop === 'never'`                          | `(timestamp: number, runGlobalEffects?: boolean) => void`                                                                                                                                                      |
| `setSize`         | Resize the canvas                                                             | `(width: number, height: number, top?: number, left?: number) => void`                                                                                                                                         |
| `setDpr`          | Set the pixel-ratio                                                           | `(dpr: number) => void`                                                                                                                                                                                        |
| `setFrameloop`    | Shortcut to set the current render mode                                       | `(frameloop?: 'always', 'demand', 'never') => void`                                                                                                                                                            |
| `setEvents`       | Shortcut to setting the event layer                                           | `(events: Partial<EventManager<any>>) => void`                                                                                                                                                                 |
| `onPointerMissed` | Response for pointer clicks that have missed a target                         | `() => void`                                                                                                                                                                                                   |
| `events`          | Pointer-event handling                                                        | `{ connected: TargetNode, handlers: Events, connect: (target: TargetNode) => void, disconnect: () => void }`                                                                                                   |

### Selector

You can also select properties, this allows you to avoid needless re-render for components that are interested only in particulars. Reactivity does not include deeper three.js internals!

```jsx
// Will only trigger re-render when the default camera is exchanged
const camera = useThree((state) => state.camera)
// Will only re-render on resize changes
const viewport = useThree((state) => state.viewport)
// ❌ You cannot expect reactivity from three.js internals!
const zoom = useThree((state) => state.camera.zoom)
```

### Reading state from outside of the component cycle

```jsx
function Foo() {
  const get = useThree((state) => state.get)
  ...
  get() // Get fresh state from anywhere you want
```

### Exchanging defaults

```jsx
function Foo() {
  const set = useThree((state) => state.set)
  ...
  useEffect(() => {
    set({ camera: new THREE.OrthographicCamera(...) })
  }, [])
```

## `useFrame`

This hook allows you to execute code on every rendered frame, like running effects, updating controls, and so on. You receive the state (same as `useThree`) and a clock delta (in seconds). Your callback function will be invoked just before a frame is rendered. When the component unmounts it is unsubscribed automatically from the render-loop.

```jsx
import { useFrame } from '@react-three/fiber'

function Foo() {
  useFrame((state, delta, xrFrame) => {
    // This function runs at the native refresh rate inside of a shared render-loop
  })
```

> [!CAUTION]
> Be careful about what you do inside useFrame! You should never setState in there! Your calculations should be slim and
> you should mind all the commonly known pitfalls when dealing with loops in general, like re-use of variables, etc.

### Taking over the render-loop

If you need more control you may pass a numerical `renderPriority` value. This will cause React Three Fiber to disable automatic rendering altogether. It will now be your responsibility to render, which is useful when you're working with effect composers, heads-up displays, etc.

```jsx
function Render() {
  // Takes over the render-loop, the user has the responsibility to render
  useFrame(({ gl, scene, camera }) => {
    gl.render(scene, camera)
  }, 1)

function RenderOnTop() {
  // This will execute *after* Render's useframe
  useFrame(({ gl, ... }) => {
    gl.render(...)
  }, 2)
```

> [!NOTE]
> Callbacks will be executed in order of ascending priority values (lowest first, highest last.), similar to the DOM's z-order.

### Negative indices

Using negative indices will **not take over the render loop**, but it can be useful if you really must order the sequence of useFrames across the component tree.

```jsx
function A() {
  // This will execute first
  useFrame(() => ..., -2)

function B() {
  // This useFrame will execute *after* A's
  useFrame(() => ..., -1)
```

## `useLoader`

This hook loads assets and suspends for easier fallback- and error-handling. It can take any three.js loader as its first argument: GLTFLoader, OBJLoader, TextureLoader, FontLoader, etc. It is based on [React.Suspense](https://react.dev/reference/react/Suspense), so fallback-handling and [error-handling](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) happen at the parental level.

```jsx
import { Suspense } from 'react'
import { useLoader } from '@react-three/fiber'
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'

function Model() {
  const result = useLoader(GLTFLoader, '/model.glb')
  // You don't need to check for the presence of the result, when we're here
  // the result is guaranteed to be present since useLoader suspends the component
  return <primitive object={result.scene} />
}

function App() {
  return (
    <Suspense fallback={<FallbackComponent /> /* or null */}>
      <Model />
    </Suspense>
  )
}
```

> [!TIP]
> Internally, `useLoader` relies on [`suspend-react`](https://github.com/pmndrs/suspend-react).

> [!NOTE]
> Assets loaded with useLoader are cached by default. The urls given serve as cache-keys. This allows you to re-use loaded data everywhere in the component tree.

> [!WARNING]
> Be very careful with mutating or disposing of loaded assets, especially when you plan to re-use them. Refer to the automatic disposal section in the API.

### Loader extensions

You can provide a callback as the third argument if you need to configure your loader:

```jsx
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader'

useLoader(GLTFLoader, url, (loader) => {
  const dracoLoader = new DRACOLoader()
  dracoLoader.setDecoderPath('/draco-gltf/')
  loader.setDRACOLoader(dracoLoader)
})
```

### Loading multiple assets at once

It can also make multiple requests in parallel:

```jsx
const [bumpMap, specMap, normalMap] = useLoader(TextureLoader, [url1, url2, url2])
```

### Loading status

You can get the loading status from a callback you provide as the fourth argument. Though consider alternatives like THREE.DefaultLoadingManager or better yet, [Drei's](https://github.com/pmndrs/drei) loading helpers.

```jsx
useLoader(loader, url, extensions, (xhr) => {
  console.log((xhr.loaded / xhr.total) * 100 + '% loaded')
})
```

### Special treatment of GLTFLoaders and all loaders that return a scene prop

If a `result.scene` prop is found the hook will automatically create a object & material collection: `{ nodes, materials }`. This lets you build immutable scene graphs selectively. You can also specifically alter the data without having to traverse it. [GLTFJSX](https://github.com/pmndrs/gltfjsx) specifically relies on this data.

```jsx
const { nodes, materials } = useLoader(GLTFLoader, url)
```

### Pre-loading assets

You can pre-load assets in global space so that models can be loaded in anticipation before they're mounted in the component tree.

```jsx
useLoader.preload(GLTFLoader, '/model.glb' /* extensions */)
```

## `useGraph`

Convenience hook which creates a memoized, named object/material collection from any [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D).

```jsx
import { useLoader, useGraph } from '@react-three/fiber'

function Model(url) {
  const scene = useLoader(OBJLoader, url)
  const { nodes, materials } = useGraph(scene)
  return <mesh geometry={nodes.robot.geometry} material={materials.metal} />
}
```
]]></page>
<page path="/api/events" title="Events"><![CDATA[URL: https://r3f.docs.pmnd.rs/api/events
Description: All the events you can hook up to


`three.js` objects that implement their own `raycast` method (meshes, lines, etc) can be interacted with by declaring events on them. We support pointer events, clicks and wheel-scroll. Events contain the browser event as well as the `three.js` event data (object, point, distance, etc). You may want to [polyfill](https://github.com/jquery/PEP) them, if that's a concern.

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)`.

Also notice the `onPointerMissed` on the canvas element, which fires on clicks that haven't hit _any_ meshes.

```jsx
<mesh
  onClick={(e) => console.log('click')}
  onContextMenu={(e) => console.log('context menu')}
  onDoubleClick={(e) => console.log('double 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')} // see note 1
  onPointerLeave={(e) => console.log('leave')} // see note 1
  onPointerMove={(e) => console.log('move')}
  onPointerMissed={() => console.log('missed')}
  onUpdate={(self) => console.log('props have been updated')}
/>
```

### Event data

```jsx
({
  ...DomEvent                   // All the original event data
  ...Intersection                 // All of Three's intersection data - see note 2
  intersections: Intersection[]    // The first intersection of each intersected object
  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                 // Distance between mouse down and mouse up event in pixels
}) => ...
```

### How the event-system works, bubbling and capture

> [!NOTE]
> - `pointerenter` and `pointerleave` events work exactly the same as pointerover and pointerout.
> - `pointerenter` and `pointerleave` semantics are not implemented.

> [!NOTE]
> Some events (such as `pointerout`) happen when there is no intersection between `eventObject` and
the ray. When this happens, the event will contain intersection data from a previous event with
this object.

### Event propagation (bubbling)

Propagation works a bit differently to the DOM because objects can occlude each other in 3D. The `intersections` array in the event includes all objects intersecting the ray, not just the nearest. Only the first intersection with each object is included.
The event is first delivered to the object nearest the camera, and then bubbles up through its ancestors like in the DOM. After that, it is delivered to the next nearest object, and then its ancestors, and so on. This means objects are transparent to pointer events by default, even if the object handles the event.

`event.stopPropagation()` doesn't just stop this event from bubbling up, it also stops it from being delivered to farther objects (objects behind this one). All other objects, nearer or farther, no longer count as being hit while the pointer is over this object. If they were previously delivered pointerover events, they will immediately be delivered pointerout events. If you want an object to block pointer events from objects behind it, it needs to have an event handler as follows:

```jsx
onPointerOver={e => {
  e.stopPropagation()
  // ...
}}
```

even if you don't want this object to respond to the pointer event. If you do want to handle the event as well as using `stopPropagation()`, remember that the pointerout events will happen **during** the `stopPropagation()` call. You probably want your other event handling to happen after this.

### Pointer capture

Because events go to all intersected objects, capturing the pointer also works differently. In the DOM, the capturing object **replaces** the hit test, but in React Three Fiber, the capturing object is **added** to the hit test result: if the capturing object was not hit, then all of the hit objects (and their ancestors) get the event first, followed by the capturing object and its ancestors. The capturing object can also use `event.stopPropagation()` so that objects that really were hit get pointerout events.

Note that you can access the `setPointerCapture` and `releasePointerCapture` methods **only** via `event.target`: they don't get added to the `Object3D` instances in the scene graph.

`setPointerCapture` and `releasePointerCapture` take a `pointerId` parameter like in the DOM, but for now they don't have support for multiple active pointers. PRs are welcome!

```jsx
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)
}}
```

### Customizing the event settings

For some advanced usage it's possible to customize the setting of the event manager globally with the `events` prop on `<Canvas/>`:

```tsx
import { Canvas, events } from '@react-three/fiber'

const eventManagerFactory: Parameters<typeof Canvas>[0]['events'] = (state) => ({
  // Default configuration
  ...events(state),

  // Determines if the event layer is active
  enabled: true,

  // Event layer priority, higher prioritized layers come first and may stop(-propagate) lower layer
  priority: 1,

  // The filter can re-order or re-structure the intersections
  filter: (items: THREE.Intersection[], state: RootState) => items,

  // The compute defines how pointer events are translated into the raycaster and pointer vector2
  compute: (event: DomEvent, state: RootState, previous?: RootState) => {
    state.pointer.set((event.offsetX / state.size.width) * 2 - 1, -(event.offsetY / state.size.height) * 2 + 1)
    state.raycaster.setFromCamera(state.pointer, state.camera)
  },

  // Find more configuration default on ./packages/fiber/src/web/events.ts
  // And type definitions in ./packages/fiber/src/core/events.ts
})

function App() {
  return (
    <Canvas events={eventManagerFactory}>
}
```

### Using a different target element

There are cases in which you may want to connect the event handlers to another DOM element instead of the canvas. This is usually done to have events on a shared parent, which allows both the canvas, and dom overlays to receive events.

You can either use the event manager:

```jsx
const events => useThree(state => state.events)
useEffect(() => {
  state.events.connect(domNode)
```

Or, the `eventSource` shortcut on the canvas (DOM only), which accepts dom-nodes and React.RefObjects to dom-nodes.

```jsx
function App() {
  const target = useRef()
  return (
    <div ref={target}>
      <Canvas eventSource={target.current}>
```

### Using a different prefix (DOM only)

By default Fiber will use offsetX/offsetY to set up the raycaster. You can change this with the `eventPrefix` shortcut.

```jsx
function App() {
  return (
    <Canvas eventPrefix="client">
```

### Allow raycast without user interaction

By default Fiber will only raycast when the user is interacting with the canvas. If, for instance, the camera moves a hoverable object underneath the cursor it will not trigger a hover event. If this is wanted behaviour you can force a raycast by executing `update()`, call it whenever necessary.

```jsx
const events => useThree(state => state.events)
useEffect(() => {
  // Will trigger a onPointerMove with the last-known pointer event
  state.events.update()
```

You can abstract this into more complex logic.

```jsx
function RaycastWhenCameraMoves() {
  const matrix = new THREE.Matrix4()
  useFrame((state) => {
    // Act only when the camera has moved
    if (!matrix.equals(state.camera.matrixWorld)) {
      state.events.update()
      matrix.copy(state.camera.matrixWorld)
    }
  })
}
```
]]></page>
<page path="/api/additional-exports" title="Additional Exports"><![CDATA[URL: https://r3f.docs.pmnd.rs/api/additional-exports


| export               | usage                                                          |
| -------------------- | -------------------------------------------------------------- |
| `addEffect`          | Adds a global render callback which is called each frame       |
| `addAfterEffect`     | Adds a global after-render callback which is called each frame |
| `addTail`            | Adds a global callback which is called when rendering stops    |
| `buildGraph`         | Collects nodes and materials from a THREE.Object3D             |
| `flushGlobalEffects` | Flushes global render-effects for when manually driving a loop |
| `flushSync`          | Force React to flush any updates synchronously and immediately |
| `invalidate`         | Forces view global invalidation                                |
| `advance`            | Advances the frameloop (given that it's set to 'never')        |
| `extend`             | Extends the native-object catalogue                            |
| `createPortal`       | Creates a portal (it's a React feature for re-parenting)       |
| `createRoot`         | Creates a root that can render three JSX into a canvas         |
| `events`             | Dom pointer-event system                                       |
| `applyProps`         | `applyProps(element, props)` sets element properties,          |
| `act`                | usage with react-testing                                       |
| `useInstanceHandle`  | Exposes react-internal local state from `instance.__r3f`       |
|                      |                                                                |
]]></page>
<page path="/api/typescript" title="TypeScript"><![CDATA[URL: https://r3f.docs.pmnd.rs/api/typescript
Description: Common scenarios and how to approach them with TypeScript


## Typing with `useRef`

React's `useRef` won't automatically infer types despite pointing it to a typed ref.

You can type the ref yourself by passing a type through `useRef`'s generics:

```tsx
import { useRef, useEffect } from 'react'
import { Mesh } from 'three'

function Box(props) {
  const meshRef = useRef<Mesh>(null!)

  useEffect(() => {
    console.log(Boolean(meshRef.current))
  }, [])

  return (
    <mesh {...props} ref={meshRef}>
      <boxGeometry />
      <meshBasicMaterial />
    </mesh>
  )
}
```

The exclamation mark is a non-null assertion that will let TS know that `ref.current` is defined when we access it in effects, useFrame et al. You do not need to check against null, the element is assumed to exist.

## Accessing typed three-elements

Whenever you want to spread props or type components that rely on three elements, you can use the `ThreeElements` interface to extract the mesh, group, or any other three element, including custom elements.

```tsx
import { ThreeElements } from '@react-three/fiber'

type FooProps = ThreeElements['mesh'] & { bar: boolean }

function Foo({ bar, ...props}: FooProps) {
  useEffect(() => {
    console.log(bar)
  }, [bar])
  return <mesh {...props} />
}
```

## Extend usage

react-three-fiber can also accept third-party elements and extend them into its internal catalogue.

```tsx
import { useRef, useEffect } from 'react'
import { GridHelper } from 'three'
import { extend } from '@react-three/fiber'

// Create our custom element
class CustomElement extends GridHelper {}

// Extend so the reconciler will learn about it
extend({ CustomElement })

<customElement />
```

The catalogue teaches the underlying reconciler how to create fibers for these elements and treat them within the scene.

You can then declaratively create custom elements with primitives, but TypeScript won't know about them nor their props.

```html
// error: 'customElement' does not exist on type 'JSX.IntrinsicElements'

<customElement />
```

### Extending ThreeElements

To define our element in JSX, we'll use the `ThreeElement` interface to extend `ThreeElements`. This interface describes three.js classes that are available in the R3F catalog and can be used as native elements.

```tsx
import { useRef, useEffect } from 'react'
import { GridHelper } from 'three'
import { extend, ThreeElement } from '@react-three/fiber'

// Create our custom element
class CustomElement extends GridHelper {}

// Extend so the reconciler will learn about it
extend({ CustomElement })

// Add types to ThreeElements elements so primitives pick up on it
declare module '@react-three/fiber' {
  interface ThreeElements {
    customElement: ThreeElement<typeof CustomElement>
  }
}

// react-three-fiber will create your custom component and TypeScript will understand it
<customComponent />
```

You can shorten element definition by using the `extend` factory signature, which will automatically extend the element locally. This will also prevent namespace bleeding.

```tsx
// Create our custom element
class CustomElement extends GridHelper {}

// Extend so the reconciler will learn about it, types will be inferred
const Element = extend(CustomElement)

// react-three-fiber will create your custom component and TypeScript will understand it
<Element />
```

## Extending three default elements

If you open your own root instead of using `<Canvas>`, you can extend the default elements with `extend`. But keep in mind that the `* as THREE` namespace contains classes, functions, numbers, strings. At the moment we suggest you use `any` or `@ts-ignore` unless you extract the exact classes you need (`extend({ Mesh, Group, ... })`).

```tsx
import * as THREE from 'three'
import { extend, createRoot, events } from '@react-three/fiber'

// Register the THREE namespace as native JSX elements.
extend(THREE as any)

// Create a react root
const root = createRoot(document.querySelector('canvas'))
```

## Exported types

react-three-fiber is extensible and exports types for its internals, such as render props, canvas props, and events:

```tsx
// Event raycaster intersection
Intersection

// `useFrame` internal subscription and render callback
Subscription
RenderCallback

// `useThree`'s returned internal state
RootState
Performance
Dpr
Size
Viewport
Camera

// Canvas props
CanvasProps

// Supported events
Events

// Event manager signature (is completely modular)
EventManager

// Wraps a platform event as it's passed through the event manager
ThreeEvent
```
]]></page>
<page path="/api/testing" title="Testing"><![CDATA[URL: https://r3f.docs.pmnd.rs/api/testing
Description: How to handle unit tests


Like with every other application testing is an important factor when it comes to releasing an application into the wild and when it comes to React Three Fiber we can use React Three Test Renderer to achieve this.

We will be testing the [sandbox](https://codesandbox.io/s/98ppy) we created in [events and interactions](events-and-interaction).

## How to test React Three Fiber

Let's start by installing the React Three Test Renderer:

```bash
npm install @react-three/test-renderer --save-dev
```

Afterwards, if you are using Create React App you can just add a file that ends in `.test.js` and start writing your code, because React Three Test Renderer is testing library agnostic, so it works with libraries such as `jest`, `jasmine` etc.

Let's create an `App.test.js` and set up all our test cases:

```jsx
import ReactThreeTestRenderer from '@react-three/test-renderer'
import { MyRotatingBox } from './App'

test('mesh to have two children', async () => {
  const renderer = await ReactThreeTestRenderer.create(<MyRotatingBox />)
})

test('click event makes box bigger', async () => {
  const renderer = await ReactThreeTestRenderer.create(<MyRotatingBox />)
})
```

In here we created three tests and in each we made sure we created the renderer by using the `create` function.

Let's start with the first test and make sure our mesh has two children, the material and cube.

We can start by getting the scene and it's children from the test instance we just created like so:

```js
const meshChildren = renderer.scene.children
```

If you log this mesh out you can see that it returns an array of one element since that's all we have in the scene.

Using this we can make sure to get that first child and use the `allChildren` property on it like so:

```js
const meshChildren = renderer.scene.children[0].allChildren
```

There is also one property called `children` but this one is meant to be used for things like groups as this one does not return the geometry and the materials, for that we need `allChildren`.

Now to create our assertion:

```js
expect(meshChildren.length).toBe(2)
```

Our first test case looks like this:

```js
test('mesh to have two children', async () => {
  const renderer = await ReactThreeTestRenderer.create(<MyRotatingBox />)
  const mesh = renderer.scene.children[0].allChildren
  expect(mesh.length).toBe(2)
})
```

## Testing interactions

Now that we have gotten the first test out of the way we can test our interaction and make sure that when we click on the mesh it does indeed update the scale.

We can do that by utilizing the `fireEvent` method existing in a test instance.

We know we can get the mesh with:

```js
const mesh = renderer.scene.children[0]
```

Since we already have that we can fire an event in it like so:

```js
await renderer.fireEvent(mesh, 'click')
```

With that done, all that's left to do is the tree demonstration of our scene and make sure the scale prop on our mesh has updated:

```js
expect(mesh.props.scale).toBe(1.5)
```

In the end our test looks something like this:

```js
test('click event makes box bigger', async () => {
  const renderer = await ReactThreeTestRenderer.create(<MyRotatingBox />)
  const mesh = renderer.scene.children[0]
  expect(mesh.props.scale).toBe(1)
  await renderer.fireEvent(mesh, 'click')
  expect(mesh.props.scale).toBe(1.5)
})
```

If you want to learn more about React Three Test Renderer you can checkout the repo and their docs:

- [Repo](https://github.com/pmndrs/react-three-fiber/blob/master/packages/test-renderer)
- [React Three Test Renderer API](https://github.com/pmndrs/react-three-fiber/blob/master/packages/test-renderer/markdown/rttr.md#create)
- [React Three Test Instance API](https://github.com/pmndrs/react-three-fiber/blob/master/packages/test-renderer/markdown/rttr-instance.md)

## Exercises

- Check the color of the Box we created
- Check the rotation using the `advanceFrames` method.

<Codesandbox id="hqut4" tests />
]]></page>
<page path="/advanced/scaling-performance" title="Scaling performance"><![CDATA[URL: https://r3f.docs.pmnd.rs/advanced/scaling-performance
Description: This is a short primer on how to scale performance.


Running WebGL can be quite expensive depending on how powerful your devices are. In order to mitigate this, especially if you want to make your application available to a broad variety of devices, including weaker options, you should look into performance optimizations. This article goes through a couple of them.

## On-demand rendering

three.js apps usually run in a game-loop that executes 60 times a second, React Three Fiber is no different. This is perfectly fine when your scene has _constantly_ moving parts in it. This is what generally drains batteries the most and makes fans spin up.

But if the moving parts in your scene are allowed to come to rest, then it would be wasteful to keep rendering. In such cases you can opt into on-demand rendering, which will only render when necessary. This saves battery and keeps noisy fans in check.

Open the sandbox below in a full screen and look into dev tools, you will see that it is completely idle when nothing is going on. It renders only when you move the model.

<Codesandbox id="wvgxp" />

All you need to do is set the canvas `frameloop` prop to `demand`. It will render frames whenever it detects prop changes throughout the component tree.

```jsx
<Canvas frameloop="demand">
```

### Triggering manual frames

One major caveat is that if anything in the tree _mutates_ props, then React cannot be aware of it and the display would be stale. For instance, camera controls just grab into the camera and mutate its values. Here you can use React Three Fiber's `invalidate` function to trigger frames manually.

```jsx
function Controls() {
  const orbitControlsRef = useRef()
  const { invalidate, camera, gl } = useThree()
  useEffect(() => {
    orbitControlsRef.current.addEventListener('change', invalidate)
    return () => orbitControlsRef.current.removeEventListener('change', invalidate)
  }, [])
  return <orbitControls ref={orbitControlsRef} args={[camera, gl.domElement]} />
```

> [!NOTE]
> Drei's controls do this automatically for you.

Generally you can call invalidate whenever you need to render:

```jsx
invalidate()
```

> [!IMPORTANT]
> Calling `invalidate()` will not render immediately, it merely requests a
new frame to be rendered out. Calling invalidate multiple times will not render multiple times.
Think of it as a flag to tell the system that something has changed.

### Sync animations with on-demand-rendering and invalidate

Since `invalidate()` is only a flag that schedules render, you might bump into syncing issues when you run animations that are synchronous (as in, they start immediately). By the time fiber renders the first frame the animation has already progressed which leads to a visible jump. In such cases you should pre-emptively schedule a render and then start the animation in the next frame.

```jsx
<mesh
  onClick={() => {
    // Pre-emptively schedule a render
    invalidate()
    // Wait for the next frame to start the animation
    requestAnimationFrame(() => controls.dolly(1, true))
  }}
```

## Re-using geometries and materials

Each geometry and material means additional overhead for the GPU. You should try to re-use resources if you know they will repeat.

You could do this globally:

```jsx
const red = new THREE.MeshLambertMaterial({ color: "red" })
const sphere = new THREE.SphereGeometry(1, 28, 28)

function Scene() {
  return (
    <>
      <mesh geometry={sphere} material={red} />
      <mesh position={[1, 2, 3]} geometry={sphere} material={red} />
```

If you create a material or color in global space - outside of React Three Fiber's `Canvas` context - you should enable [ColorManagement](https://threejs.org/docs/#manual/en/introduction/Color-management) in three.js. This will allow certain conversions (for hexadecimal and CSS colors in sRGB) to be made automatically, producing correct colors in all cases.

```jsx
import * as THREE from 'three'

// r150
THREE.ColorManagement.enabled = true

// r139-r149
THREE.ColorManagement.legacyMode = false
```

### Caching with `useLoader`

> [!NOTE]
> Every resource that is loaded with useLoader is cached automatically!

If you access a resource via useLoader with the same URL, throughout the component tree, then you will always refer to the same asset and thereby re-use it. This is especially useful if you run your GLTF assets through [GLTFJSX](https://github.com/pmndrs/gltfjsx) because it links up geometries and materials and thereby creates re-usable models.

<Codesandbox id="dix1y" />

```jsx
function Shoe(props) {
  const { nodes, materials } = useLoader(GLTFLoader, "/shoe.glb")
  return (
    <group {...props} dispose={null}>
      <mesh geometry={nodes.shoe.geometry} material={materials.canvas} />
    </group>
  )
}

<Shoe position={[1, 2, 3]} />
<Shoe position={[4, 5, 6]} />
```

## Instancing

Each mesh is a draw call, you should be mindful of how many of these you employ: no more than 1000 as the very maximum, and optimally a few hundred or less. You can win performance back by reducing draw calls, for example by instancing repeating objects. This way you can have hundreds of thousands of objects in a single draw call.

<Codesandbox id="h873k" />

Setting up instancing is not so hard, consult [the three.js docs](https://threejs.org/docs/#api/en/objects/InstancedMesh) if you need help.

```jsx
function Instances({ count = 100000, temp = new THREE.Object3D() }) {
  const instancedMeshRef = useRef()
  useEffect(() => {
    // Set positions
    for (let i = 0; i < count; i++) {
      temp.position.set(Math.random(), Math.random(), Math.random())
      temp.updateMatrix()
      instancedMeshRef.current.setMatrixAt(i, temp.matrix)
    }
    // Update the instance
    instancedMeshRef.current.instanceMatrix.needsUpdate = true
  }, [])
  return (
    <instancedMesh ref={instancedMeshRef} args={[null, null, count]}>
      <boxGeometry />
      <meshPhongMaterial />
    </instancedMesh>
  )
}
```

## Level of detail

Sometimes it can be beneficial to reduce the quality of an object the further it is away from the camera. Why would you display it full resolution if it is barely visible. This can be a good strategy to reduce the overall vertex-count which means less work for the GPU.

Scroll in and out to see the effect:

<Codesandbox id="12nmp" />

There is a small component in Drei called `<Detailed />` which sets up LOD without boilerplate. You load or prepare a couple of resolution stages, as many as you like, and then give them the same amount of distances from the camera, starting from highest quality to lowest.

```jsx
import { Detailed, useGLTF } from '@react-three/drei'

function Model() {
  const [low, mid, high] = useGLTF(["/low.glb", "/mid.glb", "/high.glb"])
  return (
    <Detailed distances={[0, 10, 20]}>
      <mesh geometry={high} />
      <mesh geometry={mid} />
      <mesh geometry={low} />
    <Detailed/>
  )
}
```

## Nested loading

Nested loading means that lesser textures and models are loaded first, higher-resolution later.

The following sandbox goes through three loading stages:

- A loading indicator
- Low quality
- High quality

<Codesandbox id="7duy8" />

And this is how easy it is to achieve it, you can nest suspense and even use it as a fallback:

```jsx
function App() {
  return (
    <Suspense fallback={<span>loading...</span>}>
      <Canvas>
        <Suspense fallback={<Model url="/low-quality.glb" />}>
          <Model url="/high-quality.glb" />
        </Suspense>
      </Canvas>
    </Suspense>
  )
}

function Model({ url }) {
  const { scene } = useGLTF(url)
  return <primitive object={scene} />
}
```

## Performance monitoring

Drei has a new component [PerformanceMonitor](https://github.com/pmndrs/drei#performancemonitor) that allows you to monitor, and adapt to, device performance. This component will collect the average fps (frames per second) over time. If after a couple of iterations the averages are below or above a threshold it will trigger onIncline and onDecline callbacks that allow you to respond. Typically you would reduce the quality of your scene, the resolution, effects, the amount of stuff to render, or, increase it if you have enough framerate to fill.

Since this would normally cause ping-ponging between the two callbacks you define upper and lower framerate bounds, as long as you stay within that margin nothing will trigger. Ideally your app should find its way into that margin by gradually altering quality.

A simple example for regulating the resolution. It starts out with 1.5, if the system falls below the bounds it goes to 1, if it's fast enough it goes to 2.

```jsx
function App() {
  const [dpr, setDpr] = useState(1.5)
  return (
    <Canvas dpr={dpr}>
      <PerformanceMonitor onIncline={() => setDpr(2)} onDecline={() => setDpr(1)} >
```

You can also use the onChange callback to get notified when the average changes in whichever direction. This allows you to make gradual changes. It gives you a factor between 0 and 1, which is increased by incline and decreased by decline. The factor is initially 0.5 by default.

```jsx
import round from 'lodash/round'

const [dpr, setDpr] = useState(1)
return (
 <Canvas dpr={dpr}>
  <PerformanceMonitor onChange={({ factor }) => setDpr(round(0.5 + 1.5 * factor, 1))}>
```

If you still experience flip flops despite the bounds you can define a limit of flipflops. If it is met onFallback will be triggered which typically sets a lowest possible baseline for the app. After the fallback has been called PerformanceMonitor will shut down.

```jsx
<PerformanceMonitor flipflops={3} onFallback={() => setDpr(1)}>
```

PerformanceMonitor can also have children, if you wrap your app in it you get to use usePerformanceMonitor which allows individual components down the nested tree to respond to performance changes on their own.

```jsx
;<PerformanceMonitor>
  <Effects />
</PerformanceMonitor>

function Effects() {
  usePerformanceMonitor({ onIncline, onDecline, onFallback, onChange })
  // ...
}
```

## Movement regression

Websites like Sketchfab make sure the scene is always fluid, running at 60 fps, and responsive, no matter which device is being used or how expensive a loaded model is. They do this by regressing movement, where effects, textures, shadows will slightly reduce quality until still-stand

The following sandbox uses expensive lights and post-processing. In order for it to run relatively smooth it will scale the pixel ratio on movement and also skip heavy post-processing effects like ambient occlusion.

<Codesandbox id="pz0q6" />

When you inspect the state model you will notice an object called `performance`.

```jsx
performance: {
  current: 1,
  min: 0.1,
  max: 1,
  debounce: 200,
  regress: () => void,
},
```

- `current`: Performance factor alternates between min and max
- `min`: Performance lower bound (should be less than 1)
- `max`: Performance upper bound (no higher than 1)
- `debounce`: Debounce timeout until it goes to upper bound (1) again
- `regress()`: Function that temporarily regresses performance

You can define defaults like so:

```jsx
<Canvas performance={{ min: 0.5 }}>...</Canvas>
```

### This is how you can put the system into regression

The only thing you have to do is call `regress()`. When exactly you do that, that is up to you, but it could be when the mouse moves, or the scene is moving, for instance when controls fire their change-event.

Say you are using controls, then the following code puts the system in regress when they are active:

```jsx
const regress = useThree((state) => state.performance.regress)
useEffect(() => {
  controls.current?.addEventListener('change', regress)
```

### This is how you can respond to it

> [!NOTE]
> Mere calls to `regress()` will not change or affect anything!

Your app has to opt into performance scaling by listening to the performance `current`! The number itself will tell you what to do. 1 (max) means everything is ok, the default. Less than 1 (min) means a regression is requested and the number itself tells you how far you should go when scaling down.

For instance, you could simply multiply `current` with the pixel ratio to cut down on resolution. If you have defined `min: 0.5` that would mean it will half the resolution for at least 200ms (delay) when regress is called. It can be used for anything else, too: switching off lights when `current < 1`, using lower-res textures, skip post-processing effects, etc. You could of course also animate/lerp these changes.

Here is a small prototype component that scales the pixel ratio:

```jsx
function AdaptivePixelRatio() {
  const current = useThree((state) => state.performance.current)
  const setPixelRatio = useThree((state) => state.setDpr)
  useEffect(() => {
    setPixelRatio(window.devicePixelRatio * current)
  }, [current])
  return null
}
```

Drop this component into the scene, combine it with the code above that calls `regress()`, and you have adaptive resolution:

```jsx
<AdaptivePixelRatio />
```

There are pre-made components for this already in the [Drei library](https://github.com/pmndrs/drei/#performance).

## Enable concurrency

React 18 introduces concurrent scheduling, specifically time slicing via `startTransition` and `useTransition`. This will virtualize the component graph, which then allows you to prioritise components and actions. Think of how a virtual list avoids scaling issues because it only renders as many items as the screen can take, it is not affected by the amount of items it has to render, be it 10 or 100.000.000.

React 18 functions very similar to this, it can potentially defer load and heavy tasks in ways that would be hard or impossible to achieve in a vanilla application. It thereby holds on to a stable framerate even in the most demanding situations.

The following benchmark shows how powerful concurrency can be: https://github.com/drcmda/scheduler-test

It simulates heavy load by creating hundreds of THREE.TextGeometry instances (510 to be exact). This class, like many others in three.js, is expensive and takes a while to construct. If all 510 instances are created the same time **it will cause approximately 1.5 seconds of pure jank** (Apple M1), the tab would normally freeze. It runs in an interval and **will execute every 2 seconds**.

|          | Distributed | At-once |
| -------- | ----------- | ------- |
| three.js | ~20fps      | ~5fps   |
| React    | ~60fps      | ~60fps  |

<p align="center">
  <img
    aria-label="three.js distributed"
    style={{ width: '50%', display: 'inline-block' }}
    src="https://github.com/drcmda/scheduler-test/raw/master/assets/three-distributed.jpg"
  />
  <img
    aria-label="three.js at once"
    style={{ width: '50%', display: 'inline-block' }}
    src="https://github.com/drcmda/scheduler-test/raw/master/assets/three-at-once.jpg"
  />
  <img
    aria-label="React distributed"
    style={{ width: '50%', display: 'inline-block' }}
    src="https://github.com/drcmda/scheduler-test/raw/master/assets/react-distributed.jpg"
  />
  <img
    aria-label="React at once"
    style={{ width: '50%', display: 'inline-block' }}
    src="https://github.com/drcmda/scheduler-test/raw/master/assets/react-at-once.jpg"
  />
</p>

For more on how to use this API, see [use startTransition for expensive ops](/advanced/pitfalls#✅-use-starttransition-for-expensive-ops).
]]></page>
<page path="/advanced/pitfalls" title="Performance pitfalls"><![CDATA[URL: https://r3f.docs.pmnd.rs/advanced/pitfalls
Description: Performance 1x1


## Tips and Tricks

This is a good overview: https://discoverthreejs.com/tips-and-tricks

The most important gotcha in three.js is that creating objects can be expensive, think twice before you mount/unmount things! Every material or light that you put into the scene has to compile, every geometry you create will be processed. Share materials and geometries if you can, either in global scope or locally:

```jsx
const geom = useMemo(() => new BoxGeometry(), [])
const mat = useMemo(() => new MeshBasicMaterial(), [])
return items.map(i => <mesh geometry={geom} material={mat} ...
```

Try to use [instancing](https://codesandbox.io/s/r3f-instanced-colors-8fo01) as much as you can when you need to display many objects of a similar type!

## Avoid setState in loops

TLDR, don't, mutate inside `useFrame`!

- Threejs has a render-loop, it does not work like the DOM does. **Fast updates are carried out in `useFrame` by mutation**. `useFrame` is your per-component render-loop.

- It is not enough to set values in succession, _you need frame deltas_. Instead of `position.x += 0.1` consider `position.x += delta` or your project will run at different speeds depending on the end-users system. Many updates in threejs need to be paired with update flags (`.needsUpdate = true`), or imperative functions (`.updateProjectionMatrix()`).

- You might be tempted to setState inside `useFrame` but there is no reason to. You would only complicate something as simple as an update by routing it through React's scheduler, triggering component render etc.

### ❌ `setState` in loops is bad

```jsx
useEffect(() => {
  const interval = setInterval(() => setX((x) => x + 0.1), 1)
  return () => clearInterval(interval)
}, [])
```

### ❌ `setState` in useFrame is bad

```jsx
const [x, setX] = useState(0)
useFrame(() => setX((x) => x + 0.1))
return <mesh position-x={x} />
```

### ❌ `setState` in fast events is bad

```jsx
<mesh onPointerMove={(e) => setX((x) => e.point.x)} />
```

### ✅ Instead, just mutate, use deltas

In general you should prefer useFrame. Consider mutating props safe as long as the component is the only entity that mutates. Use deltas instead of fixed values so that your app is refresh-rate independent and runs at the same speed everywhere!

```jsx
const meshRef = useRef()
useFrame((state, delta) => (meshRef.current.position.x += delta))
return <mesh ref={meshRef} />
```

Same goes for events, use references.

```jsx
<mesh onPointerMove={(e) => (ref.current.position.x = e.point.x)} />
```

If you must use intervals, use references as well, but keep in mind that this is not refresh-rate independent.

```jsx
useEffect(() => {
  const interval = setInterval(() => ref.current.position.x += 0.1, 1)
  return () => clearInterval(interval)
}, [])
```

## Handle animations in loops

The frame loop is where you should place your animations. For instance using lerp, or damp.

### ✅ Use `lerp` + `useFrame`

```jsx
function Signal({ active }) {
  const meshRef = useRef()
  useFrame((state, delta) => {
    meshRef.current.position.x = THREE.MathUtils.lerp(meshRef.current.position.x, active ? 100 : 0, 0.1)
  })
  return <mesh ref={meshRef} />
```

### ✅ Or react-spring

Or, use animation libraries. React-spring has its own frame-loop and animates outside of React. Framer-motion is another popular alternative.

```jsx
import { a, useSpring } from '@react-spring/three'

function Signal({ active }) {
  const { x } = useSpring({ x: active ? 100 : 0 })
  return <a.mesh position-x={x} />
```

## Do not bind to fast state reactively

Using state-managers and selective state is fine, but not for updates that happen rapidly for the same reason as above.

### ❌ Don't bind reactive fast-state

```jsx
import { useSelector } from 'react-redux'

// Assuming that x gets animated inside the store 60fps
const x = useSelector((state) => state.x)
return <mesh position-x={x} />
```

### ✅ Fetch state directly

For instance using [Zustand](https://github.com/pmndrs/zustand) (same in Redux et al).

```jsx
useFrame(() => (ref.current.position.x = api.getState().x))
return <mesh ref={ref} />
```

## Don't mount indiscriminately

In threejs it is very common to not re-mount at all, see the ["disposing of things"](https://discoverthreejs.com/tips-and-tricks/) section in discover-three. This is because buffers and materials get re-initialized/compiled, which can be expensive.

### ❌ Avoid mounting runtime

```jsx
{
  stage === 1 && <Stage1 />
}
{
  stage === 2 && <Stage2 />
}
{
  stage === 3 && <Stage3 />
}
```

### ✅ Consider using visibility instead

```jsx
<Stage1 visible={stage === 1} />
<Stage2 visible={stage === 2} />
<Stage3 visible={stage === 3} />

function Stage1(props) {
  return (
    <group {...props}>
      ...
```

### ✅ Use `startTransition` for expensive ops

React 18 introduces the `startTransition` and `useTransition` APIs to defer and schedule work and state updates. Use these to de-prioritize expensive operations.

Since version 8 of Fiber canvases use concurrent mode by default, which means React will schedule and defer expensive operations. You don't need to do anything, but you can play around with the [experimental scheduler](https://github.com/drcmda/scheduler-test) and see if marking ops with a lesser priority makes a difference.

```jsx
import { useTransition } from 'react'
import { Points } from '@react-three/drei'

const [isPending, startTransition] = useTransition()
const [radius, setRadius] = useState(1)
const positions = calculatePositions(radius)
const colors = calculateColors(radius)
const sizes = calculateSizes(radius)

<Points
  positions={positions}
  colors={colors}
  sizes={sizes}
  onPointerOut={() => {
    startTransition(() => {
      setRadius(prev => prev + 1)
    })
  }}
>
  <meshBasicMaterial vertexColors />
</Points>
```

## Don't re-create objects in loops

Try to avoid creating too much effort for the garbage collector, re-pool objects when you can!

### ❌ Bad news for the GC

This creates a new vector 60 times a second, which allocates memory and forces the GC to eventually kick in.

```jsx
useFrame(() => {
  ref.current.position.lerp(new THREE.Vector3(x, y, z), 0.1)
})
```

### ✅ Better re-use object

Set up re-used objects in global or local space, now the GC will be silent.

```jsx
function Foo(props)
  const vec = new THREE.Vector()
  useFrame(() => {
    ref.current.position.lerp(vec.set(x, y, z), 0.1)
  })
```

## `useLoader` instead of plain loaders

Threejs loaders give you the ability to load async assets (models, textures, etc), but if you do not re-use assets it can quickly become problematic.

### ❌ No re-use is bad for perf

This re-fetches, re-parses for every component instance.

```jsx
function Component() {
  const [texture, set] = useState()
  useEffect(() => void new TextureLoader().load(url, set), [])
  return texture ? (
    <mesh>
      <sphereGeometry />
      <meshBasicMaterial map={texture} />
    </mesh>
  ) : null
}
```

Instead use useLoader, which caches assets and makes them available throughout the scene.

### ✅ Cache and re-use objects

```jsx
function Component() {
  const texture = useLoader(TextureLoader, url)
  return (
    <mesh>
      <sphereGeometry />
      <meshBasicMaterial map={texture} />
    </mesh>
  )
}
```

Regarding GLTF's try to use [GLTFJSX](https://github.com/pmndrs/gltfjsx) as much as you can, this will create immutable JSX graphs which allow you to even re-use full models.
]]></page>
<page path="/tutorials/v9-migration-guide" title="v9 Migration Guide"><![CDATA[URL: https://r3f.docs.pmnd.rs/tutorials/v9-migration-guide
Description: Changes and new features with v9 and React 19


This is a compatibility release for React 19, which brings further performance, stability, and type improvements. You can check out the React 19 changelog [here](https://react.dev/blog/2024/04/25/react-19).

We would like to express our gratitude to the community for their continued support, as well as to all our contributors, including the React team at Meta and Vercel, for ensuring this upgrade went smoothly. 🎉

> [!WARNING]  
> This release contains breaking changes when using Strict Mode, which can highlight bugs during development. See [StrictMode](#strictmode).

## Features

### useLoader Accepts Loader Instance

`useLoader` now supports re-use of external loader instances for more controlled pooling and setup.

```jsx
import { GLTFLoader } from 'three/addons'
import { useLoader } from '@react-three/fiber'

function Model() {
  const gltf = useLoader(GLTFLoader, '/path/to/model.glb')
  // ...
}

// or,

const loader = new GLTFLoader()
function Model() {
  const gltf = useLoader(loader, '/path/to/model.glb')
  // ...
}
```

### Factory extend Signature

`extend` can now produce a component when a three.js class is passed to it individually instead of a catalog of named classes. This is backwards compatible and reduces TypeScript boilerplate and JSX collisions. We recommend libraries migrate to this signature so internal components don't clash with user-land declarations.

```tsx
import { OrbitControls } from 'three/addons'
import { type ThreeElement, type ThreeElements } from '@react-three/fiber'

declare module '@react-three/fiber' {
  interface ThreeElements {
    orbitControls: ThreeElement<typeof OrbitControls>
  }
}

extend({ OrbitControls })

<orbitControls args={[camera, gl.domElement]}>

// or,

const Controls = extend(OrbitControls)
<Controls args={[camera, gl.domElement]} />
```

### Async GL prop

The Canvas GL prop accepts constructor parameters, properties, or a renderer instance via a callback. The callback now passes constructor parameters instead of just a canvas reference.

```diff
<Canvas
  gl={{ reverseDepthBuffer: true }}
- gl={(canvas) => new WebGLRenderer({ canvas })}
+ gl={(props) => new WebGLRenderer(props)}
>
```

Further, a callback passed to GL can now return a promise for async constructors like `WebGPURenderer` (see [WebGPU](#webgpu)).

```tsx
<Canvas
  gl={async (props) => {
    // ...
    return renderer
  }}
>
````

## WebGPU

Recent Three.js now includes a WebGPU renderer. While still a work in progress and not fully backward-compatible with all of Three's features, the renderer requires an async initialization method. R3F streamlines this by allowing the gl prop to return a promise.

```tsx
import * as THREE from 'three/webgpu'
import * as TSL from 'three/tsl'
import { Canvas, extend, useFrame, useThree } from '@react-three/fiber'

declare module '@react-three/fiber' {
  interface ThreeElements extends ThreeToJSXElements<typeof THREE> {}
}

extend(THREE as any)

export default () => (
  <Canvas
    gl={async (props) => {
      const renderer = new THREE.WebGPURenderer(props as any)
      await renderer.init()
      return renderer
    }}>
      <mesh>
        <meshBasicNodeMaterial />
        <boxGeometry />
      </mesh>
  </Canvas>
)
```

## Fixes

### Color Management of Textures

Automatic sRGB conversion of texture props has been removed. Color textures are now handled automatically for built-in materials, aligning with vanilla Three.js behavior. This prevents issues where data textures (e.g., normals or displacement) become corrupted or non-linear. For custom materials or shaders, annotate color textures with `texture.colorSpace = THREE.SRGBColorSpace` or `texture-colorSpace={THREE.SRGBColorSpace}` in JSX.

For more details, see https://threejs.org/docs/#manual/en/introduction/Color-management.

### Suspense and Side-Effects

The handling of Suspense and fallback content has improved in React and R3F. Side-effects like attach and constructor effects (e.g., controls adding event listeners) no longer fire repeatedly without proper cleanup during suspension.

```jsx
import { ThreeElement, useThree } from '@react-three/fiber'
import { OrbitControls } from 'three/addons'

declare module '@react-three/fiber' {
  interface ThreeElements {
    OrbitControls: ThreeElement<typeof OrbitControls>
  }
}

extend({ OrbitControls })

function Controls() {
  const camera = useThree((state) => state.camera)
  const gl = useThree((state) => state.gl)

  // Will only initialize when tree is connected to screen
  return <orbitControls args={[camera, gl.domElement]}>
}

<Suspense>
  <Controls />
  <AsyncComponent />
</Suspense>
```

### Swapping with args and primitives

Swapping elements when changing the `args` or primitive `object` prop has been improved for structured children like arrays or iterators (React supports both, including async iterators). Previously, primitives sharing an object could update out of order or be removed from the scene along with their children.

See: https://github.com/pmndrs/react-three-fiber/pull/3272

## TypeScript Changes

### Props renamed to CanvasProps

Canvas `Props` is now called `CanvasProps` for clarity. These were aliased in v8 for forward compatibility, but `Props` is removed with v9.

```diff
-function Canvas(props: Props)
+function Canvas(props: CanvasProps)
```

### Dynamic JSX Types

Since R3F's creation, JSX types had to be maintained in accordance with additions to three core API. Although missing or future types could be ignored or resilient for forward and backwards compatibility, this was a major maintenance burden for us and those extending three. Furthermore, libraries which wrap or bind to the known catalog of elements (e.g. React Spring `<animated.mesh />`) had no way of knowing which elements belonged to a renderer.

Since v8, we've added a catalog of known elements to a `ThreeElements` interface, and with v9 automatically map three API to JSX types. As types are now dynamically mapped, hardcoded exports like `MeshProps` have been removed, and can be accessed as `ThreeElements['mesh']`. Helper types like `Color` or `Vector3` remain to reflect the JSX `MathType` API for shorthand expression.

```diff
-import { MeshProps } from '@react-three/fiber'
-type Props = MeshProps

+import { ThreeElements } from '@react-three/fiber'
+type Props = ThreeElements['mesh']
```

### Node Helpers

Specialized `Node` type helpers for extending JSX (`Node`, `Object3DNode`, `BufferGeometryNode`, `MaterialNode`, `LightNode`) are removed and combined into 'ThreeElement', which accepts a single type representing the extended element instance.

```tsx
import { type ThreeElement } from '@react-three/fiber'

declare module '@react-three/fiber' {
  interface ThreeElements {
    customElement: ThreeElement<typeof CustomElement>
  }
}

extend({ CustomElement })
```

### ThreeElements

`ThreeElements` was added as an interface since v8.1.0 and is the current way of declaring or accessing JSX within R3F since React's depreciation of `global` JSX (see https://react.dev/blog/2024/04/25/react-19-upgrade-guide#the-jsx-namespace-in-typescript). All JSX types belonging to R3F are accessible from `ThreeElements`.

```diff
-import { type Node } from '@react-three/fiber'
-
-declare global {
-  namespace JSX {
-    interface IntrinsicElements {
-      customElement: Node<CustomElement, typeof CustomElement>
-    }
-  }
-}
-
-extend({ CustomElement })

+import { type ThreeElement } from '@react-three/fiber'
+
+declare module '@react-three/fiber' {
+  interface ThreeElements {
+    customElement: ThreeElement<typeof CustomElement>
+  }
+}
+
+extend({ CustomElement })
```

## Testing

### StrictMode

`StrictMode` is now correctly inherited from a parent renderer like react-dom. Previously, `<StrictMode />` mounted in another root such as react-dom would not affect the R3F canvas, so it had to be redeclared within the canvas as well.

```diff
<StrictMode>
  <Canvas>
-    <StrictMode>
-      // ...
-    </StrictMode>
+    // ...
  </Canvas>
</StrictMode>
```

Keep in mind, this change may affect the behavior of your application. If you encounter anything that worked before and fails now, profile it first in dev and then production. If it works in prod then strict mode has flushed out a side-effect in your code.

### Act

`act` is now exported from React itself and can be used for all renderers. It will return the contents of a passed async callback like before and recursively flush async effects to synchronously test React output.

```tsx
import { act } from 'react'
import { createRoot } from '@react-three/fiber'

const store = await act(async () => createRoot(canvas).render(<App />))
console.log(store.getState())
```
]]></page>
<page path="/tutorials/events-and-interaction" title="Events and Interaction"><![CDATA[URL: https://r3f.docs.pmnd.rs/tutorials/events-and-interaction
Description: Let's make our meshes react to user input.


This tutorial will assume some React knowledge, and will be based on [this starter codesandbox](https://codesandbox.io/s/getting-started-01-12q81?from-embed), so just fork it and follow along!

After we have our continuous loop running the next step would be to allow our mesh to react to user interaction, so in this part let's attach a click handler to the cube and make it bigger on click.

## User Interaction

Any Object3D that has a raycast method can receive a large number of events, for instance a mesh:

```jsx
<mesh
  onClick={(e) => console.log('click')}
  onContextMenu={(e) => console.log('context menu')}
  onDoubleClick={(e) => console.log('double 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')}
  onPointerMissed={() => console.log('missed')}
  onUpdate={(self) => console.log('props have been updated')}
/>
```

From this we can see that what we need to do is use the old `onClick` event we use on any DOM element to react to a user clicking the mesh.

Let's add it then:

```jsx
<mesh onClick={() => alert('Hellooo')}>
  <boxGeometry />
  <meshPhongMaterial color="royalblue" />
</mesh>
```

We did it! We created the most boring interaction in the story of 3D and we made an alert show up. Now let's make it actually animate our mesh.

Let's start by setting some state to check if the mesh is active:

```jsx
const [active, setActive] = useState(false)
```

After we have this we can set the scale with a ternary operator like so:

```jsx
<mesh scale={active ? 1.5 : 1} onClick={() => setActive(!active)}>
  <boxGeometry />
  <meshPhongMaterial color="royalblue" />
</mesh>
```

If you try to click on your mesh now, it scales up and down. We just made our first interactive 3D mesh!

What we did in this chapter was:

- Attached a click handler to our mesh
- Added some state to track if the mesh is currently active
- Changed the scale based on that state

<Codesandbox id="98ppy" />

**Exercises**

- Change other props of the mesh like the `position` or even the `color` of the material.
- Use `onPointerOver` and `onPointerOut` to change the props of the mesh on hover events.

## Next steps

We just made our mesh react to user interaction but it looks pretty bland without any transition, right?
In the next chapter let's integrate `react-spring` into our project to make this into an actual animation.
]]></page>
<page path="/tutorials/loading-models" title="Loading Models"><![CDATA[URL: https://r3f.docs.pmnd.rs/tutorials/loading-models
Description: 3D Software to the web!


> All the models in this page were created by Sara Vieira and are freely available to download from any of the sandboxes.

There are many types of 3D model extensions, in this page we will focus on loading the three most common ones: `GLTF`, `FBX` and `OBJ`. All of these will use the `useLoader` function but in slightly different ways.

This whole section will assume you have placed your models in the public folder or in a place in your application where you can import them easily.

## Loading GLTF models

Starting with the open standard and the one that has more support in React Three Fiber we will load a `.gltf` model.

Let's start by importing the two things we need:

```js
import { useLoader } from '@react-three/fiber'
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'
```

With this we can create a Model component and place it in our scene like so:

```jsx
function Scene() {
  const gltf = useLoader(GLTFLoader, '/Poimandres.gltf')
  return <primitive object={gltf.scene} />
}
```

You can play with the sandbox and see how it looks here after I added an HDRI background:

<Codesandbox id="6etx1" />

### Loading GLTF models as JSX Components

Here comes the really fancy part, you can transform these models into React components and then use them as you would any React component.

To do this, grab your `GLTF` model and head over to [https://gltf.pmnd.rs/](https://gltf.pmnd.rs/) and drop your `GLTF`, after that you should see something like:

![gltfjsx](gltfjsx.png)

Let's now copy the code and move it over to `Model.js`:

```jsx
/*
Auto-generated by: https://github.com/pmndrs/gltfjsx
*/

import React, { useRef } from 'react'
import { useGLTF } from '@react-three/drei'

export default function Model(props) {
  const groupRef = useRef()
  const { nodes, materials } = useGLTF('/Poimandres.gltf')
  return (
    <group ref={groupRef} {...props} dispose={null}>
      <mesh castShadow receiveShadow geometry={nodes.Curve007_1.geometry} material={materials['Material.001']} />
      <mesh castShadow receiveShadow geometry={nodes.Curve007_2.geometry} material={materials['Material.002']} />
    </group>
  )
}

useGLTF.preload('/Poimandres.gltf')
```

Now we can import our model like we would import any React component and use it in our app:

```jsx
import { Suspense } from 'react'
import { Canvas } from '@react-three/fiber'
import { Environment } from '@react-three/drei'

import Model from './Model'

export default function App() {
  return (
    <div className="App">
      <Canvas>
        <Suspense fallback={null}>
          <Model />
          <Environment preset="sunset" background />
        </Suspense>
      </Canvas>
    </div>
  )
}
```

You can play with the sandbox here:

<Codesandbox id="vbnbf" />

## Loading OBJ models

In this case, we will use the trusted `useLoader` hook but in combination with `three.js` `OBJLoader`.

```js
import { OBJLoader } from 'three/addons/loaders/OBJLoader.js'
import { useLoader } from '@react-three/fiber'
```

With these imported let's get the mesh into our scene:

```jsx
function Scene() {
  const obj = useLoader(OBJLoader, '/Poimandres.obj')
  return <primitive object={obj} />
}
```

And here we go, we have an OBJ model showing on the web! Pretty cool ah?

You can play with the sandbox here:

<Codesandbox id="51zks" />

## Loading FBX models

Let's again use the trusted `useLoader` but this time with the `FBXLoader` that comes from `three.js`

```js
import { useLoader } from '@react-three/fiber'
import { FBXLoader } from 'three/addons/loaders/FBXLoader.js'
```

To create our scene we can get the FBX as a return value of `useLoader` by passing `FBXLoader` and the location of our file like so:

```jsx
function Scene() {
  const fbx = useLoader(FBXLoader, '/Poimandres.fbx')
  return <primitive object={fbx} />
}
```

You can play with the sandbox here:

<Codesandbox id="ssrfg" />

### Loading FBX models using `useFBX`

[@react-three/drei](https://github.com/pmndrs/drei) exports a very useful helper when it comes to loading FBX models and it's called `useFBX`, in this case there is no need to import anything from `three.js` as it is all done behind the scenes and we can just pass the location of the file to `useFBX` like so:

```jsx
function Scene() {
  const fbx = useFBX('/Poimandres.fbx')
  return <primitive object={fbx} />
}
```

You can play with the sandbox here:

<Codesandbox id="m6p73" />

## Showing a loader

If your model is big and takes a while to load, it's always good to show a small loader of how much is already is loaded and again [@react-three/drei](https://github.com/pmndrs/drei) is here to help with `Html` and `useProgress`.

- `Html` allows you place plain ol' HTML in your canvas and render it like you would a normal DOM element.
- `useProgress` is a hook that gives you a bunch of information about the loading status of your model.

With these two things, we can create a very bare-bones loading component like so:

```jsx
import { Html, useProgress } from '@react-three/drei'

function Loader() {
  const { progress } = useProgress()
  return <Html center>{progress} % loaded</Html>
}
```

We can then wrap our model in it using `Suspense` like so:

```jsx
export default function App() {
  return (
    <Canvas>
      <Suspense fallback={<Loader />}>
        <Model />
      </Suspense>
    </Canvas>
  )
}
```

The hook returns much more than just the progress so there is a lot you can do there to give the user more information about the loading status of the application. You can play with all of them in this sandbox:

<Codesandbox id="nn2m7" />
]]></page>
<page path="/tutorials/loading-textures" title="Loading Textures"><![CDATA[URL: https://r3f.docs.pmnd.rs/tutorials/loading-textures
Description: Let's load some fancy textures.


> All textures used in this chapter were downloaded from [cc0textures](https://cc0textures.com/).

## Using `TextureLoader` and `useLoader`

To load the textures we will use the `TextureLoader` from three.js in combination with `useLoader` that will allow us to pass the location of the texture and get the map back.

It's better to explain with code, let's say you downloaded [this texture](https://cc0textures.com/view?id=PavingStones092) and placed it in the public folder of your site, to get the color map from it you could do:

```js
const colorMap = useLoader(TextureLoader, 'PavingStones092_1K_Color.jpg')
```

Let's then with this information create a small scene where we can use this texture:

```jsx
import { Suspense } from 'react'
import { Canvas, useLoader } from '@react-three/fiber'
import { TextureLoader } from 'three'

function Scene() {
  const colorMap = useLoader(TextureLoader, 'PavingStones092_1K_Color.jpg')
  return (
    <>
      <ambientLight intensity={0.2} />
      <directionalLight />
      <mesh>
        <sphereGeometry args={[1, 32, 32]} />
        <meshStandardMaterial />
      </mesh>
    </>
  )
}

export default function App() {
  return (
    <Canvas>
      <Suspense fallback={null}>
        <Scene />
      </Suspense>
    </Canvas>
  )
}
```

If everything went according to plan, you should now be able to apply this texture to the sphere like so:

```jsx
<meshStandardMaterial map={colorMap} />
```

Awesome! That works but we have a lot more textures to import and do we have to create a different useLoader for each of them?

That's the great part! You don't, the second argument is an array where you can pass all the textures you have and the maps will be returned and ready to use:

```js
const [colorMap, displacementMap, normalMap, roughnessMap, aoMap] = useLoader(TextureLoader, [
  'PavingStones092_1K_Color.jpg',
  'PavingStones092_1K_Displacement.jpg',
  'PavingStones092_1K_Normal.jpg',
  'PavingStones092_1K_Roughness.jpg',
  'PavingStones092_1K_AmbientOcclusion.jpg',
])
```

Now we can place them in our mesh like so:

```jsx
<meshStandardMaterial
  map={colorMap}
  displacementMap={displacementMap}
  normalMap={normalMap}
  roughnessMap={roughnessMap}
  aoMap={aoMap}
/>
```

The displacement will probably be too much, usually setting it to 0.2 will make it look good. Our final code would look something like:

```jsx
function Scene() {
  const [colorMap, displacementMap, normalMap, roughnessMap, aoMap] = useLoader(TextureLoader, [
    'PavingStones092_1K_Color.jpg',
    'PavingStones092_1K_Displacement.jpg',
    'PavingStones092_1K_Normal.jpg',
    'PavingStones092_1K_Roughness.jpg',
    'PavingStones092_1K_AmbientOcclusion.jpg',
  ])
  return (
    <mesh>
      {/* Width and height segments for displacementMap */}
      <sphereGeometry args={[1, 100, 100]} />
      <meshStandardMaterial
        displacementScale={0.2}
        map={colorMap}
        displacementMap={displacementMap}
        normalMap={normalMap}
        roughnessMap={roughnessMap}
        aoMap={aoMap}
      />
    </mesh>
  )
}
```

## Using `useTexture`

Another way to import these is using `useTexture` from [`@react-three/drei`](https://github.com/pmndrs/drei), that will make it slightly easier and there is no need to import the `TextureLoader`, our code would look like:

```js
import { useTexture } from "@react-three/drei"

...

const [colorMap, displacementMap, normalMap, roughnessMap, aoMap] = useTexture([
  'PavingStones092_1K_Color.jpg',
  'PavingStones092_1K_Displacement.jpg',
  'PavingStones092_1K_Normal.jpg',
  'PavingStones092_1K_Roughness.jpg',
  'PavingStones092_1K_AmbientOcclusion.jpg',
])
```

You can also use object-notation which is the most convenient:

```jsx
const props = useTexture({
  map: 'PavingStones092_1K_Color.jpg',
  displacementMap: 'PavingStones092_1K_Displacement.jpg',
  normalMap: 'PavingStones092_1K_Normal.jpg',
  roughnessMap: 'PavingStones092_1K_Roughness.jpg',
  aoMap: 'PavingStones092_1K_AmbientOcclusion.jpg',
})

return (
  <mesh>
    <sphereGeometry args={[1, 32, 32]} />
    <meshStandardMaterial {...props} />
  </mesh>
)
```

You can play with the sandbox and see how it looks:

<Codesandbox id="rusfd" />
]]></page>
<page path="/tutorials/basic-animations" title="Basic Animations"><![CDATA[URL: https://r3f.docs.pmnd.rs/tutorials/basic-animations
Description: This guide will help you understand refs, useFrame and how to make basic animations with Fiber


This tutorial will assume some React knowledge, and will be based on [this starter codesandbox](https://codesandbox.io/s/getting-started-01-12q81?from-embed), so just fork it and follow along!

We will build a really small, continuous animation loop, that will be the basic building block of more advanced animations later on.

## `useFrame`

`useFrame` is a Fiber hook that lets you execute code on every frame of Fiber's render loop. This can have a lot of uses, but we will focus on building an animation with it.

It's important to remember that **Fiber hooks can only be called inside a `<Canvas />` parent**!

```jsx
import { useFrame } from '@react-three/fiber'

function MyAnimatedBox() {
  useFrame(() => {
    console.log("Hey, I'm executing every frame!")
  })
  return (
    <mesh>
      <boxGeometry />
      <meshBasicMaterial color="royalblue" />
    </mesh>
  )
}
```

This loop is the basic building block of our animation, the callback we pass to `useFrame` will be executed every frame and it will be passed an object containing the state of our Fiber scene:

For example, we can extract time information from the `clock` parameter, to know how much time has elapsed in our application, and use that time to animate a value:

```jsx
useFrame(({ clock }) => {
  const a = clock.elapsedTime
  console.log(a) // the value will be 0 at scene initialization and grow each frame
})
```

`clock` is a [three.js Clock](https://threejs.org/docs/#api/en/core/Clock) object, from which we are getting the total elapsed time, which will be key for our animations.

## Animating with Refs

It would be tempting to just update the state of our component via `setState` and let it change the `mesh` via props, but going through state isn't ideal, when dealing with continuous updates, commonly know as [transient updates]().
Instead, we want to **directly mutate our mesh each frame**. First, we'll have to get a `reference` to it, via the `useRef` React hook:

```jsx
import React from 'react'

function MyAnimatedBox() {
  const myMesh = React.useRef()
  return (
    <mesh ref={myMesh}>
      <boxGeometry />
      <meshBasicMaterial color="royalblue" />
    </mesh>
  )
}
```

`myMesh` will now hold a reference to the actual three.js object, which we can now freely mutate in `useFrame`, without having to worry about React:

```jsx
useFrame(({ clock }) => {
  myMesh.current.rotation.x = clock.elapsedTime
})
```

Let's have a closer look:

- We are destructuring `clock` from the argument passed to `useFrame`, which we know is the state of our Fiber scene.
- We are accessing the `rotation.x` property of `myMesh.current` object, which is a reference to our mesh object
- We are assigning our time-dependent value `a` to the `rotation` on the `x` axis, meaning our object will now infinitely rotate between -1 and 1 radians around the x axis!

<Codesandbox id="29gxw" />

**Exercises**

- Try `Math.sin(clock.elapsedTime)` and see how your animation changes

## Next steps

Now that you understand the basic technique for animating in Fiber, [learn how event works](/tutorials/events-and-interaction)!

If you want to go deeper into animations, check these out:

- [Animating with React Spring](/tutorials/using-with-react-spring)
]]></page>
<page path="/tutorials/how-it-works" title="How does it work?"><![CDATA[URL: https://r3f.docs.pmnd.rs/tutorials/how-it-works
Description: This is an advanced guide on the inner workings of Fiber, if you are just getting started, take a look at our introduction!


React Three Fiber is a React <a href="https://reactjs.org/docs/codebase-overview.html#renderers">renderer</a> for **three.js**.

This means that each Fiber component will effectively create a new THREE object that will be added to a `scene`.
Understanding how this works is not necessarily needed to use Fiber, but it will better arm you to deal with anything that you might need in your projects, reading other people's Fiber code and even help you contribute.

Let's take a small React example:

```jsx
import { Canvas } from '@react-three/fiber'

function MyApp() {
  return (
    <Canvas>
      <group>
        <mesh>
          <meshNormalMaterial />
          <boxGeometry args={[2, 2, 2]} />
        </mesh>
      </group>
    </Canvas>
  )
}
```

In three.js, this is equivalent to:

```js
import * as THREE from 'three'

const scene = new THREE.Scene() // <Canvas>

const group = new THREE.Group() // <group>

const mesh = new THREE.Mesh() // <mesh />
const material = new THREE.MeshNormalMaterial() // <meshNormalMaterial />
const geometry = new THREE.BoxGeometry(2, 2, 2) // <boxGeometry />

mesh.material = material
mesh.geometry = geometry

group.add(mesh)
scene.add(group)
```

Our `Canvas` element will create a new scene, and Fiber will instantiate new objects for each component and correctly compose them together in a scene graph!

Additionally, Fiber will:

- Setup a new perspective camera at [0, 0, 0] and set it as default
- Setup a **render loop** with automatic render to screen
- Setup pointer events via raycasting on all meshes with `onPointer` props
- Setup tone mapping
- Automatically handle window resize

**Let's break this down!**

## Creating THREE objects

In three.js, we can create new object using the classic JS API:

```js
const myBox = new THREE.BoxGeometry(1, 2, 3)
```

Object creation is handled transparently by the Fiber renderer, the name of the constructor `BoxGeometry` is equivalent to the camel case component `<boxGeometry />`, while the constructor arguments - in our example `[1, 2, 3]` - are passed via the `args` prop:

```jsx
<boxGeometry args={[1, 2, 3]} />
```

> [!NOTE]
> Note that the object will be created only when first adding the component to the React tree!

## The `attach` props

Fiber always tries to correctly infer the relationship between components and their parents, for example:

```jsx
<group>
  <mesh />
</group>
```

Here, we always know that a group can only have children, so Fiber just calls the `add` method on the group:

```js
group.add(mesh)
```

For meshes and other three.js objects, rules can be different. Looking at the three.js documentation, we can see how a `THREE.Mesh` object is constructed using a `material` and a `geometry`.

With the `attach` prop, we can precisely tell the renderer what property to attach each component to:

```jsx
<mesh>
  <meshNormalMaterial attach="material" />
  <boxGeometry attach="geometry" />
</mesh>
```

This will _explicitly_ tell Fiber to render like this:

```js
mesh.material = new THREE.MeshNormalMaterial()
mesh.geometry = new THREE.BoxGeometry()
```

As you can see, the `attach` prop is telling Fiber to set the parent's `material` property to a reference to our `<meshNormalMaterial />` object.

Note that while we used geometry and material for this example, Fiber also infers the attach property from the
constructor name, so anything with `material` or `geometry` will automatically get attached to the correct property of
its parent.

## Props

With Fiber, you can pass any three.js property as a React property, and it will be assigned to the constructed object:

```jsx
<meshBasicMaterial color="red" />
```

is equivalent to:

```jsx
const material = new THREE.MeshBasicMaterial()
material.color = 'red'
```

Fiber will check the type of the property value and either:

- assign the new value directly
- if the value is an object with a `set` method, call that
- construct a new object if needed.
- convert between formats

```jsx
<mesh scale={[1, 2, 3]} />
```

is equivalent to:

```jsx
const mesh = new THREE.Mesh()
mesh.scale = new THREE.Vector3(1, 2, 3)

// on update, it will instead `set()` the vector
mesh.scale.set(3, 4, 5)
```

## Pointer Events

[Pointer Events](/api/events) are transparently handled by Fiber. On startup, it will create a [raycaster](https://threejs.org/docs/#api/en/core/Raycaster) for mouse picking.

Every object with `onPointer` props will be added to the array of objects checked every frame by the raycaster:

```jsx
<mesh onPointerDown={console.log}>...</mesh>
```

The ray's `origin` and `direction` are updated every time the mouse moves on the `<Canvas />` element or the window is resized.
Fiber also handles camera switching, meaning that the raycaster will always use the currently active camera.

When using the `raycast` prop, the object will instead be picked using a custom ray:

```jsx
import { useCamera } from '@react-three/drei'

return <mesh raycast={useCamera(anotherCamera)} />
```

## Render Loop

By default, Fiber will setup a render loop that renders the default `scene` from the default `camera` to a [WebGLRenderer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer).

The loop is setup using [setAnimationLoop](https://threejs.org/docs/#api/en/renderers/WebGLRenderer.setAnimationLoop), which will execute its callback every time a new frame is renderable. This is what will happen every render:

1. All global before effects are executed
2. Clock delta is saved - implying all `useFrame` calls will share the same `delta`
3. `useFrame` callbacks are executed in order
4. `renderer.render(scene, camera)` is called, effectively rendering the scene to screen
5. All global after effects are executed
]]></page>