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

### Why?

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

#### Does it have limitations?

None. Everything that works in three.js will work here without exception.

#### Can it keep up with frequent updates to three.js?

Yes. There is no hard dependency on a particular three.js version, it does not wrap or duplicate a single three.js class. It merely expresses three.js in JSX: `<mesh />` becomes `new THREE.Mesh()`, and that happens dynamically.

#### Is it slower than plain three.js?

No. There is no additional overhead. Components participate in a unified renderloop outside of React. It outperforms three.js in scale due to Reacts scheduling abilities.

### What does it look like?

<table>
  <tr>
    <td>
      Let's make a re-usable component that has its own state, reacts to user-input and participates
      in the render-loop. (
      <a href="https://codesandbox.io/s/rrppl0y8l4?file=/src/App.js">live demo</a>).
    </td>
    <td>
      <a href="https://codesandbox.io/s/rrppl0y8l4">
        <img src="https://i.imgur.com/sS4ArrZ.gif" />
      </a>
    </td>
  </tr>
</table>

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

function Box(props) {
  // This reference will give us direct access to the mesh
  const mesh = useRef()
  // Set up state for the hovered and active state
  const [hovered, setHover] = useState(false)
  const [active, setActive] = useState(false)
  // Subscribe this component to the render-loop, rotate the mesh every frame
  useFrame((state, delta) => (mesh.current.rotation.x += 0.01))
  // Return view, these are regular three.js elements expressed in JSX
  return (
    <mesh
      {...props}
      ref={mesh}
      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>
  )
}

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

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

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

```tsx
import * as THREE from 'three'
import ReactDOM from 'react-dom'
import React, { useRef, useState } from 'react'
import { Canvas, useFrame } from '@react-three/fiber'

function Box(props: JSX.IntrinsicElements['mesh']) {
  const mesh = useRef<THREE.Mesh>(null!)
  const [hovered, setHover] = useState(false)
  const [active, setActive] = useState(false)
  useFrame((state, delta) => (mesh.current.rotation.x += 0.01))
  return (
    <mesh
      {...props}
      ref={mesh}
      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>
  )
}

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

Live demo: https://codesandbox.io/s/icy-tree-brnsm?file=/src/App.tsx

</details>

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

This example uses `expo-cli` for the sake of simplicity, but you can use your own barebones setup if you wish.

```bash
# Install expo-cli, this will create our app
npm install expo-cli -g

# Create app and cd into it
expo init my-app
cd my-app

# Install dependencies
npm install three @react-three/fiber@beta react@beta

# Start
expo start
```

```tsx
import * as THREE from 'three'
import React, { useRef, useState } from 'react'
import { Canvas, useFrame } from '@react-three/fiber/native'

function Box(props) {
  const mesh = useRef(null)
  const [hovered, setHover] = useState(false)
  const [active, setActive] = useState(false)
  useFrame((state, delta) => (mesh.current.rotation.x += 0.01))
  return (
    <mesh
      {...props}
      ref={mesh}
      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 />
      <pointLight position={[10, 10, 10]} />
      <Box position={[-1.2, 0, 0]} />
      <Box position={[1.2, 0, 0]} />
    </Canvas>
  )
}
```

</details>

---

### Fundamentals

You need to be versed in both React and `three.js` before rushing into this. If you are unsure about React consult the official [React docs](https://reactjs.org/docs/getting-started.html), especially [the section about hooks](https://reactjs.org/docs/hooks-reference.html). As for `three.js`, make sure you at least glance over the following links:

- Make sure you have a [basic grasp of `three.js`](https://threejs.org/docs/index.html#manual/en/introduction/Creating-a-scene). Keep that site open.
- 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).
- [Look up](https://threejs.org/docs/index.html#api/en/objects/Mesh) the JSX elements that you see (mesh, ...), _all_ three.js exports are native to React Three Fiber.
- Try changing some values, scroll through our [API](/react-three-fiber/API/canvas) to see what the various settings and hooks do.

### Some reading material:

- [three.js-docs](https://threejs.org/docs)
- [three.js-examples](https://threejs.org/examples)
- [three.js-fundamentals](https://threejsfundamentals.org)
- [Discover three.js](https://discoverthreejs.com)
- [Do's and don'ts](https://discoverthreejs.com/tips-and-tricks) for performance and best practices
- [react-three-fiber alligator.io tutorial](https://alligator.io/react/react-with-threejs) by [@dghez\_](https://twitter.com/dghez_)

### Ecosystem

- [`@react-three/gltfjsx`](https://github.com/react-spring/gltfjsx) &ndash; turns GLTFs into JSX components
- [`@react-three/drei`](https://github.com/react-spring/drei) &ndash; useful helpers for react-three-fiber
- [`@react-three/postprocessing`](https://github.com/react-spring/react-postprocessing) &ndash; post-processing effects
- [`@react-three/flex`](https://github.com/react-spring/react-three-flex) &ndash; flexbox for react-three-fiber
- [`@react-three/xr`](https://github.com/react-spring/react-xr) &ndash; VR/AR controllers and events
- [`@react-three/cannon`](https://github.com/react-spring/use-cannon) &ndash; physics based hooks
- [`@react-three/a11y`](https://github.com/pmndrs/react-three-a11y) &ndash; accessibility tools for react-three-fiber
- [`zustand`](https://github.com/react-spring/zustand) &ndash; state management
- [`react-spring`](https://github.com/react-spring/react-spring) &ndash; a spring-physics-based animation library
- [`react-use-gesture`](https://github.com/react-spring/react-use-gesture) &ndash; mouse/touch gestures

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

### 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" />
</a>

### 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" />
</a>


React-three-fiber is a React renderer for three.js.

Introduction

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

> Fiber is compatible with React v16.8+ and works with ReactDOM and React Native.

Getting started with React Three Fiber is not nearly has 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:

- Create React App
- Next.js
- Expo


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

## Create React App

`create-react-app` will work out of the box, nothing special here!

## Next.js

It should work out of the box but you will encounter untranspiled add-ons in the three.js ecosystem, in that case 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!

## Expo & React Native

This example uses `expo-cli` for the sake of simplicity, but you can use your own barebones setup if you wish.

```bash
# Install expo-cli, this will create our app
npm install expo-cli -g

# Create app and cd into it
expo init my-app
cd my-app

# Install dependencies
npm install three @react-three/fiber@beta react@beta

# Start
expo start
```

Just import from native targets and that's it!

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

## Without build tools

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

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

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

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

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

const html = htm.bind(React.createElement)

function Box(props) {
  const mesh = useRef()
  const [hovered, setHover] = useState(false)
  const [active, setActive] = useState(false)
  useFrame(() => (mesh.current.rotation.x = mesh.current.rotation.y += 0.01))
  return html` <mesh
    ...${props}
    ref=${mesh}
    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>

Installation


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 ReactDOM from 'react-dom'
import { Canvas } from '@react-three/fiber'

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

ReactDOM.render(<App />, document.getElementById('root'))
```

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

<Hint>
  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.
</Hint>

## 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 />
```

<Hint>
  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.
</Hint>

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](https://docs.pmnd.rs/react-three-fiber/API/objects#dealing-with-objects-that-are-normally-not-part-of-the-scene-and-attaching) to their parent.

```jsx
<Canvas>
  <mesh>
    <boxGeometry />
    <meshStandardMaterial />
  </mesh>
```

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]} />
```

<Hint>Note that every time you change args, the object must be re-constructed!</Hint>

## 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](/react-three-fiber/API/objects).

## The result

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

<Codesandbox id="12q81" />

## Exercise

- 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


This guide will help you setup your first React Three Fiber scene and introduce you to its core concepts.

Your first scene


## Showcase

<Grid cols={1}>
  <li>
    <Sandbox id="l4klb" />
  </li>
</Grid>
<Grid cols={2}>
  <li>
    <Sandbox id="kv7tv" />
  </li>
  <li>
    <Sandbox id="4m0d0" />
  </li>
  <li>
    <Sandbox id="ls503" />
  </li>
  <li>
    <Sandbox id="n60qg" />
  </li>
</Grid>
<Grid cols={4}>
  <li>
    <Sandbox id="gsm1y" />
  </li>
  <li>
    <Sandbox id="x8gvs" />
  </li>
  <li>
    <Sandbox id="yjhzv" />
  </li>
  <li>
    <Sandbox id="kud9p" />
  </li>
  <li>
    <Sandbox id="zgsyn" />
  </li>
  <li>
    <Sandbox id="i6t0j" />
  </li>
  <li>
    <Sandbox id="h8o2d" />
  </li>
  <li>
    <Sandbox id="ni6v4" />
  </li>
  <li>
    <Sandbox id="wu51m" />
  </li>
  <li>
    <Sandbox id="zxpv7" />
  </li>
  <li>
    <Sandbox id="9keg6" />
  </li>
  <li>
    <Sandbox id="pz0q6" />
  </li>
  <li>
    <Sandbox id="9b56t" />
  </li>
  <li>
    <Sandbox id="tu24h" />
  </li>
  <li>
    <Sandbox id="qxjoj" />
  </li>
  <li>
    <Sandbox id="qf8d0" />
  </li>
  <li>
    <Sandbox id="jz9l97qn89" />
  </li>
  <li>
    <Sandbox id="prb9t" />
  </li>
  <li>
    <Sandbox id="pecl6" />
  </li>
  <li>
    <Sandbox id="sbf2i" />
  </li>
  <li>
    <Sandbox id="dvokj" />
  </li>
  <li>
    <Sandbox id="bfplr" />
  </li>
  <li>
    <Sandbox id="c671i" />
  </li>
  <li>
    <Sandbox id="nsb7f" />
  </li>
  <li>
    <Sandbox id="wsg13" />
  </li>
  <li>
    <Sandbox id="32zuv" />
  </li>
  <li>
    <Sandbox id="t4l0f" />
  </li>
  <li>
    <Sandbox id="wdzv4" />
  </li>
  <li>
    <Sandbox id="6hi1y" />
  </li>
  <li>
    <Sandbox id="9p4j7" />
  </li>
  <li>
    <Sandbox id="1sccp" />
  </li>
  <li>
    <Sandbox id="q23sw" />
  </li>
  <li>
    <Sandbox id="gpioq" />
  </li>
  <li>
    <Sandbox id="f5sgi" />
  </li>
  <li>
    <Sandbox id="3rjsl" />
  </li>
  <li>
    <Sandbox id="4j2q2" />
  </li>
  <li>
    <Sandbox id="mvkqs" />
  </li>
  <li>
    <Sandbox id="dh2jc" />
  </li>
  <li>
    <Sandbox id="gkfhr" />
  </li>
  <li>
    <Sandbox id="0buje" />
  </li>
  <li>
    <Sandbox id="9eeo2" />
  </li>
  <li>
    <Sandbox id="5oufp" />
  </li>
  <li>
    <Sandbox id="0n9it" />
  </li>
  <li>
    <Sandbox id="f1ixt" />
  </li>
  <li>
    <Sandbox id="7psew" />
  </li>
  <li>
    <Sandbox id="vl221" />
  </li>
  <li>
    <Sandbox id="oep9o" />
  </li>
  <li>
    <Sandbox id="w633u" />
  </li>
  <li>
    <Sandbox id="kmb9i" />
  </li>
  <li>
    <Sandbox id="tx1pq" />
  </li>
  <li>
    <Sandbox id="ddk57" />
  </li>
  <li>
    <Sandbox id="jflps" />
  </li>
</Grid>

## Game prototypes

<Grid>
  <li>
    <Sandbox id="lo6kp" occlude />
  </li>
  <li>
    <Sandbox id="rmfcq" occlude />
  </li>
  <li>
    <Sandbox id="i2160" occlude />
  </li>
  <li>
    <Sandbox id="vkgi6" occlude />
  </li>
  <li>
    <Sandbox id="2yqpv" occlude />
  </li>
  <li>
    <Sandbox id="0mgum" occlude />
  </li>
  <li>
    <Sandbox id="66cd7" occlude />
  </li>
  <li>
    <Sandbox id="ebr0x" occlude />
  </li>
</Grid>

## Basic examples

<Grid>
  <li>
    <Sandbox id="rrppl0y8l4" occlude />
  </li>
  <li>
    <Sandbox id="btsbj" occlude />
  </li>
  <li>
    <Sandbox id="rz2g0" occlude />
  </li>
  <li>
    <Sandbox id="8fo01" occlude />
  </li>
  <li>
    <Sandbox id="7duy8" occlude />
  </li>
  <li>
    <Sandbox id="k8phr" occlude />
  </li>
  <li>
    <Sandbox id="dix1y" occlude />
  </li>
  <li>
    <Sandbox id="zcuqh" occlude />
  </li>
  <li>
    <Sandbox id="7ucso" occlude />
  </li>
  <li>
    <Sandbox id="py4db" occlude />
  </li>
  <li>
    <Sandbox id="hf1cs" occlude />
  </li>
  <li>
    <Sandbox id="39hg8" occlude />
  </li>
  <li>
    <Sandbox id="wbrfs" occlude />
  </li>
  <li>
    <Sandbox id="itfgk" occlude />
  </li>
  <li>
    <Sandbox id="iup24" occlude />
  </li>
  <li>
    <Sandbox id="zu2wo" occlude />
  </li>
  <li>
    <Sandbox id="1g4qq" occlude />
  </li>
  <li>
    <Sandbox id="z8e6m" occlude />
  </li>
  <li>
    <Sandbox id="h545c" occlude />
  </li>
  <li>
    <Sandbox id="0k27n" occlude />
  </li>
  <li>
    <Sandbox id="d36mw" occlude />
  </li>
  <li>
    <Sandbox id="h873k" occlude />
  </li>
  <li>
    <Sandbox id="08s1u" occlude />
  </li>
  <li>
    <Sandbox id="wvgxp" occlude />
  </li>
  <li>
    <Sandbox id="5xho4" occlude />
  </li>
  <li>
    <Sandbox id="mbfzf" occlude />
  </li>
  <li>
    <Sandbox id="mkq8e" occlude />
  </li>
  <li>
    <Sandbox id="12nmp" occlude />
  </li>
  <li>
    <Sandbox id="6oei7" occlude />
  </li>
  <li>
    <Sandbox id="3k4g6" occlude />
  </li>
  <li>
    <Sandbox id="3878x" occlude />
  </li>
  <li>
    <Sandbox id="1b40u" occlude />
  </li>
  <li>
    <Sandbox id="0ycwe" occlude />
  </li>
  <li>
    <Sandbox id="veyr7" occlude />
  </li>
  <li>
    <Sandbox id="enx1u" occlude />
  </li>
  <li>
    <Sandbox id="yup2o" occlude />
  </li>
  <li>
    <Sandbox id="ib0jc" occlude />
  </li>
</Grid>


A few examples that demostrate what you can do with React Three Fiber

Examples


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>
      <sphereBufferGeometry />
      <meshStandardMaterial color="hotpink" />
    </mesh>
  </Canvas>
)
```

The props available for the canvas are:

| Prop            | Description                                                                                                                                       | Default                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| children        | three.js JSX elements or regular components                                                                                                       |                                                          |
| gl              | Props that go into the default renderer, or your own renderer. Also accepts a synchronous callback like `gl={canvas => new Renderer({ canvas })}` | `{}`                                                     |
| camera          | Props that go into the default camera, or your own `THREE.Camera`                                                                                 | `{ fov: 75, near: 0.1, far: 1000, position: [0, 0, 5] }` |
| shadows         | Props that go into `gl.shadowMap`, can also be set true for `PCFsoft`                                                                             | `false`                                                  |
| raycaster       | Props that go into the default raycaster                                                                                                          | `{}`                                                     |
| vr              | Switches renderer to VR mode, then uses `gl.setAnimationLoop`                                                                                     | `false`                                                  |
| mode            | React mode: legacy, blocking, concurrent                                                                                                          | `blocking`                                               |
| 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]                                                                              | `undefined`                                              |
| linear          | Switch off automatic sRGB encoding and gamma correction                                                                                           | `false`                                                  |
| 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) => {}`                                          |

The canvas props should be used as a _constructor_. To update the canvas props, set the state like this:

```jsx
const set = useThree((state) => state.set)
set({ frameloop: 'demand' })
```

### Defaults that the canvas component sets up

Canvas will create a translucent `THREE.WebGLRenderer` with the following properties:

- antialias=true
- alpha=true
- powerPreference="high-performance"
- setClearAlpha(0)
- 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`
- A [resize observer](https://github.com/react-spring/react-use-measure)

<Hint>
  The colorspace will be set to sRGB (unless "linear" is true), all colors and textures will be
  auto-converted. Consult [donmccurdy.com: Color Management in
  three.js](https://www.donmccurdy.com/2020/06/17/color-management-in-threejs) for more information
  about this. Unless "flat" is true it will set up `THREE.ACESFilmicToneMapping` for slightly more
  contrast.
</Hint>

<Hint>
  Consider Resize-Observer polyfills for older Safari browsers. We recommend
  https://github.com/juggle/resize-observer
</Hint>


The Canvas object is your portal into three.js.

Canvas


As of version 6 you may use a render function, similar to how `react-dom` and all the other React renderers work. This allows you to shave off `react-dom` (~40kb), `react-use-measure` + `resize-observer-polyfill` (~5kb) and, if you don't need them, `pointer-events` (~7kb) (you need to explicitly import `events` and add them to the config otherwise).

The render functions config has 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.

```jsx
import React from 'react'
import { render, events } from '@react-three/fiber'

window.addEventListener('resize', () =>
  render(<mesh />, document.querySelector('canvas'), {
    events,
    size: { width: window.innerWidth, height: window.innerHeight },
  })
)

window.dispatchEvent(new Event('resize'))
```

To unmount and dispose of all the memory that has been acquired:

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

unmountComponentAtNode(document.querySelector('canvas'))
```


Render Function


## 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/index.html#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/index.html#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" />
```

<Hint>
  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.
</Hint>

### 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} />
```

## 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">
```

<Hint>
  All native elements ending with "Material" receive attach="material", and all elements ending with
  "Geometry" receive attach="geometry". So you do not have to type it out any longer.
</Hint>

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

### Nesting

You can nest primitive objects, too:

```jsx
<mesh>
  <meshBasicMaterial attach="material">
    <texture attach="map" image={img} onUpdate={self => (self.needsUpdate = true)} />
```

### AttachArray

Sometimes attaching isn't enough. The following example attaches effects to an array called "passes" of the parent `effectComposer`. `attachArray` adds the object to the target array and takes it out on unmount:

```jsx
<effectComposer>
  <renderPass attachArray="passes" scene={scene} camera={camera} />
  <glitchPass attachArray="passes" renderToScreen />
```

### AttachObject

You can also attach to named parent properties using `attachObject={[target, name]}`, which adds the object and takes it out on unmount. The following adds a buffer-attribute to `parent.attributes.position`.

```jsx
<bufferGeometry attach="geometry">
  <bufferAttribute attachObject={['attributes', 'position']} count={v.length / 3} array={v} itemSize={3} />
```

### AttachFns

Some objects have special add/remove function, you can't easily attach objects. In that case `attachFns` gives you full control.

The following uses the effect composer from the [vanruesc/postprocessing](https://github.com/vanruesc/postprocessing) library, which works differently than three/examples/jsm. You need to call `Composer.addPass` to add an effect and `Composer.removePass` to remove it.

```jsx
<effectComposer>
  <renderPass attachFns={["addPass", "removePass"]} args={[scene, camera]} />
```

And in the case the add/remove functions are more complex:

```jsx
<effectComposer>
  <renderPass
    args={[scene, camera]}
    attachFns={[
      (parent, self) => parent.addPass(self),
      (parent, self) => parent.removePass(self)
    ]} />
```

## 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]} />
```

## 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]} />
```

## 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 />
```

## 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} />
```


All the effective ways of using React Three Fiber

Objects, properties and constructor arguments


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.

<Hint>Hooks can only be used inside the Canvas element because they rely on context!</Hint>

❌ 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`                                                                                                                                                                                      |
| mouse           | Contains updated, normalized, centric pointer coordinates | `THREE.Vector2`                                                                                                                                                                                                |
| clock           | Running system clock                                      | `THREE.Clock`                                                                                                                                                                                                  |
| vr              | True when the system is in VR mode                        | `boolean`                                                                                                                                                                                                      |
| linear          | True when the colorspace is linear                        | `boolean`                                                                                                                                                                                                      |
| flat            | True when no tonemapping is used                          | `boolean`                                                                                                                                                                                                      |
| frameloop       | React render-mode                                         | `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 }`                                                                                                                                                                            |
| viewport        | Viewport size in three.js units                           | `{ width: number, height: number, initialDpr: number, dpr: number, factor: number, distance: number, aspect: number, getCurrentViewport: (camera?: Camera, target?: THREE.Vector3, size?: Size) => Viewport }` |
| 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) => void`                                                                                                                                                                      |
| setDpr          | Set the pixel-ratio                                       | `(dpr: number) => 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. 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) => {
    // This function runs 60 times/second inside the global render-loop
  })
```

<Hint>
  Be careful about what you do inside useFrame! You should never setState in there! You 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.
</Hint>

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

<Hint>
  Callbacks will be executed in order of ascending priority values (lowest first, highest last.),
  similar to the DOM's z-order.
</Hint>

### 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(() => ..., -1)

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

## 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://reactjs.org/docs/concurrent-mode-suspense.html), so fallback-handling and [error-handling](https://reactjs.org/docs/error-boundaries.html) 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>
  )
}
```

<Hint>
  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.
</Hint>

<Hint>
  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.
</Hint>

### 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, material } = 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 } 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} />
}
```


Hooks


`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

<Hint>
  the <InlineCode>pointerenter</InlineCode> and <InlineCode>pointerleave</InlineCode> events work
  exactly the same as pointerover and pointerout. The
  <InlineCode>pointerenter</InlineCode> and <InlineCode>pointerleave</InlineCode> semantics are not implemented.
</Hint>

<Hint>
  Some events (such as pointerout) happen when there is no intersection between
  <InlineCode>eventObject</InlineCode> and the ray. When this happens, the event will contain intersection
  data from a previous event with this object.
</Hint>

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


Events


| 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    |
| 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)       |
| render                 | Renders three JSX into a canvas                                |
| unmountComponentAtNode | Unmounts root scene                                            |
| events                 | Dom pointer-event system                                       |
| applyProps             | `applyProps(element, props)` sets element properties,          |
| act                    | usage with react-testing                                       |
|                        |                                                                |


Additional Exports


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 ref = useRef()
  const { invalidate, camera, gl } = useThree()
  useEffect(() => {
    ref.current.addEventListener('change', invalidate)
    return () => ref.current.removeEventListener('change', invalidate)
  }, [])
  return <orbitControls ref={ref} args={[camera, gl.domElement]} />
```

<Hint>
  Drei's controls do this automatically for you. If you use react-spring to animate your scene then
  it will also take care of it.
</Hint>

Generally you can call invalidate whenever you need to render:

```jsx
invalidate()
```

<Hint>
  Calling <InlineCode>invalidate()</InlineCode> 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.
</Hint>

## 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} />
```

### Caching with useLoader

<Hint>Every resource that is loaded with useLoader is cached automatically!</Hint>

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/index.html?q=instance#api/en/objects/InstancedMesh) if you need help.

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

## 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 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

<Hint>Mere calls to regress() will not change or affect anything!</Hint>

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 pixelratio 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.setPixelRatio)
  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 will introduce concurrent scheduling, specifically time slicing. 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.

You can already use it in current React Three Fiber.

```jsx
<Canvas mode="concurrent">
```

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>

<Hint>
  Until React 18 comes out officially the concurrency option in React Three Fiber is experimental!
</Hint>


This is a short primer on how to scale performance.

Scaling performance


## 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 BoxBufferGeometry(), [])
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!

## Never, ever, setState in loops!

SetState in React is not adequate for fast updates, for instance in order to move or animate something, or even if you receive fast data from somewhere: remote, events, etc. Avoid forcing a full component (+ its children) through React and its diffing mechanism 60 times per second!

### ❌ setState in loops is bad

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

### ❌ setState in fast intervals is bad

```jsx
useEffect(() => void setInterval(() => setX((x) => x + 0.1), 1), [])
```

### ❌ setState in fast events is bad

```jsx
<mesh onPointerMove={() => setX((x) => x + 0.1)} />
```

### ✅ Instead, use refs and mutate

This is why useFrame exists! Consider mutating props safe as long as the component is the only entity that mutates.

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

And the same goes for intervals and events, just use references!

```jsx
useEffect(() => void setInterval(() => (ref.current.position.x += 0.01), 1), [])
```

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

## Don't let React near animations

Instead use lerp, or animation libs that animate outside of React! Avoid libs like react-motion that re-render the component 60fps!

### ✅ Use lerp + useFrame

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

### ✅ Or react-spring

React-spring has its own frame-loop and animates outside of React.

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

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

## Never bind fast state reactive

Using state-managers and selective state is fine, but not for updates that happen rapidly!

### ❌ 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/react-spring/zustand).

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

### ✅ Or, subscribe transiently

See: [transient updates for often occurring state changes](https://github.com/react-spring/zustand#transient-updates-for-often-occuring-state-changes).

```jsx
const ref = useRef()
useEffect(
  () =>
    api.subscribe(
      (x) => (ref.current.position.x = x),
      (state) => state.x
    ),
  []
)
return <mesh ref={ref} />
```

## Don't mount indiscriminately

In three.js 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 materials get re-compiled, etc.

### ✅ Use concurrent mode

Switch React to `@experimental` and flag the canvas as concurrent. Now React will schedule and defer expensive operations. You don't need to do anything else, 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
<Canvas mode="concurrent" />
```

## Don't re-create objects in loops

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

### ❌ This is 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({ vec = new THREE.Vector(), ...props })
  useFrame(() => {
    ref.current.position.lerp(vec.set(x, y, z), 0.1)
  })
```

## useLoader instead of plain loaders

three.js loaders give you the ability to load async assets (models, textures, etc), but they are 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.


Performance pitfalls


### Consuming context from a foreign provider

At the moment React context [can not be readily used between two renderers](https://github.com/pmndrs/react-three-fiber/issues/43), this is due to a problem within React. If ReactDOM opens up a provider, you will not be able to consume it within `<Canvas>`. If managing state (like Redux) is your problem, then [Zustand](https://github.com/react-spring/zustand) is likely the best solution, otherwise you can solve it by forwarding the context object that you are trying to access:

```jsx
function App() {
  const value = useContext(context)
  return (
    <Canvas>
      <context.Provider value={value}>
        {/* children can now read state from context */}
```

There's also a ready-made solution in Drei: [useContextBridge](https://github.com/pmndrs/drei#usecontextbridge) which allows you to forward contexts provided above the `<Canvas />` to be consumed within it.

```jsx
import { useContextBridge } from "@react-three/drei"

function SceneWrapper() {
  // bridge any number of contexts
  const ContextBridge = useContextBridge(ThemeContext, GreetingContext)
  return (
    <Canvas>
      <ContextBridge>
        <Scene />
      </ContextBridge>
    </Canvas>
  )
}

function Scene() {
  // we can now consume a context within the Canvas
  const theme = React.useContext(ThemeContext)
  const greeting = React.useContext(GreetingContext)
  return (
    //...
  )
}
```


Gotchas


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 mesh in React Three Fiber has a large number of events, 13 to be more precise:

```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')} ref={myMesh}>
  <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)} ref={myMesh}>
  <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.


Let's make our meshes react to user input.

Events and Interaction


> 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/examples/jsm/loaders/GLTFLoader'
```

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 (
    <Suspense fallback={null}>
      <primitive object={gltf.scene} />
    </Suspense>
  )
}
```

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 your 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](/react-three-fiber/getting-started/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 group = useRef()
  const { nodes, materials } = useGLTF('/Poimandres.gltf')
  return (
    <group ref={group} {...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/examples/jsm/loaders/OBJLoader'
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/examples/jsm/loaders/FBXLoader'
```

To create our scene we can get the FBX as a return value of the useLoader by passing the `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" />


Loading Models


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

## Using TextureLoader & 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/src/loaders/TextureLoader'

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" />


Loading Textures


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.getElapsedTime()
  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.getElapsedTime()
})
```

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.getElapsedTime())` and see how your animation changes

## Next steps

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

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

- [Animating with React Spring](using-with-react-spring)
- [Animating with GSAP]()


This guide will help you understand refs, useFrame and how to make basic animations with Fiber

Basic Animations


This tutorial will assume some React knowledge, and will be based on [this starter codesandbox](https://codesandbox.io/s/interaction-98ppy?file=/src/App.js), so just fork it and follow along!

We learned out to create small animations and also how to react to user interaction but we did not learn yet how to change these props in a way it creates an animation.

For that we are gonna use `react-spring`, `react-spring` is spring physics based animation library and it works perfectly with React Three Fiber as it comes from the same maintainers and it also has exports created specifically for use with React Three Fiber.

## Spring Animations

Let's start by defining some concepts about `react-spring` as it works with animations in a way you may not be used to, usually when defining an animation or even a transition in CSS you tell the code how much time you want the transition to last.

```css
transition: opacity 200ms ease;
```

This is not how `react-spring` works, it instead works with `springs` and what that means is that how the animations flows depends on things like the mass, tension and friction of what you want to animate and this is exactly what makes it so perfect to use with 3D.

## Using `react-spring`

Let's start by installing it:

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

After that we will importing everything from `@react-spring/three` as it contains the components that were created specifically for use with React Three Fiber.

We will need to import two things from `react-spring`:

```js
import { useSpring, animated } from '@react-spring/three'
```

Let's go over them, shall we?

- `useSpring` - A hook to transform values into animated-values
- `animated` - A component that is used instead of your DOM or mesh, so instead of using `mesh` you will `animated.mesh` if you want it to be affected by `react-spring`

Let's create our first spring and attach it to our mesh when the user clicks.

```js
const springs = useSpring({ scale: active ? 1.5 : 1 })
```

What we did here is create a constant called `springs` and this constant will hold the animated values.

`useSpring` itself takes one argument, and that is an object with all the things you want to animate. In this case, we just want to animate the scale and to hop between the value of 1 and the value of 1.5 depending on the active state.

We can also deconstruct the return value of `useSpring` and just get the value we want, like so:

```js
const { scale } = useSpring({ scale: active ? 1.5 : 1 })
```

Now that we have this animated value let's place it in our mesh:

```jsx
<animated.mesh scale={scale} onClick={() => setActive(!active)} ref={myMesh}>
  <boxGeometry />
  <meshPhongMaterial color="royalblue" />
</animated.mesh>
```

If you now click on the cube you can see that it doesn't just jump from one value to the other but instead it animates smoothly between the two values.

One last touch I want to do is add is a bit of a wobblier effect to the animation and for that we can import the `config` object from `react-spring`:

```js
import { useSpring, animated, config } from '@react-spring/three'
```

Lastly when we call the hook we can pass a value for config and lets pass the `wobbly` configuration:

```js
const { scale } = useSpring({
  scale: active ? 1.5 : 1,
  config: config.wobbly,
})
```

If this configuration is not your favorite you can check out all of them at the [`react-spring` documentation](https://react-spring.io).

What we did in this chapter was:

- Learn how to use `react-spring` with React Three Fiber
- Animate props in our 3D Mesh

<Codesandbox id="gykbc" />

** Exercises **

- Animate the position of the mesh using `react-spring`

** Further Reading **

- [React Spring Documentation](https://www.react-spring.io/)


Using with React Spring


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 />


Testing

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 />
          <boxBufferGeometry 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.BoxBufferGeometry(2, 2, 2) // <boxBufferGeometry />

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!

<Callout>
  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
</Callout>

**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.BoxBufferGeometry(1, 2, 3)
```

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

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

<Callout>
  Note that the object will be created only when first adding the component the React three!
</Callout>

## 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" />
  <boxBufferGeometry attach="geometry" />
</mesh>
```

This will _explicitly_ tell Fiber to render like this:

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

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

<Callout>
  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.
</Callout>

The same is true for `attachArray` which, instead of setting the property, will push to an existing array:

```jsx
<effectComposer>
  <renderPass attachArray="passes" scene={scene} camera={camera} />
  <glitchPass attachArray="passes" renderToScreen />
```

## 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](/react-three-fiber/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/fiber'

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

_Add about opting out of render_

This is an advanced guide on the inner workings of Fiber, if you are just getting started, take a look at our introduction!

How does it work?


<div id="intro-demos">
  <div className="demo-cell">
    <a
      target="_blank"
      rel="nofollow noopener noreferrer"
      href="https://codesandbox.io/embed/n9vo1my91p"
    >
      <img src="https://i.imgur.com/tg1mN1F.gif" className="laptop" />
    </a>
  </div>
  <a
    target="_blank"
    rel="nofollow noopener noreferrer"
    href="https://codesandbox.io/embed/j0y0vpz59"
  >
    <div className="demo-cell">
      <img src="https://i.imgur.com/OxGLHeT.gif" className="tablet" />
    </div>
  </a>
  <a
    target="_blank"
    rel="nofollow noopener noreferrer"
    href="https://codesandbox.io/embed/01p1kxymow"
  >
    <div className="demo-cell">
      <img src="https://i.imgur.com/ifdCBvG.gif" className="phone" />
    </div>
  </a>
</div>
<p align="middle">
  <i>These demos are real, click them!</i>
</p>

**react-spring** is a spring-physics based animation library that should cover most of your UI related animation needs. It gives you tools flexible enough to confidently cast your ideas into moving interfaces.

This library represents a modern approach to animation. It is very much inspired by Christopher Chedeau's [animated](https://github.com/animatedjs/animated) and Cheng Lou's [react-motion](https://github.com/chenglou/react-motion). It inherits animated's powerful interpolations and performance, as well as react-motion's ease of use. But while animated is mostly imperative and react-motion mostly declarative, react-spring bridges both. You will be surprised how easy static data is cast into motion with small, explicit utility functions that don't necessarily affect how you form your views.

## Installation

To install the entire `react-spring` library:

```shell
yarn add react-spring
```

## Platforms

react-spring is cross platform, it supports the web, react-native, react-native-web and practically any other platform, we have specifically exported the following targets (these are available to install as opposed to the entire module to fit your use case):

```bash
@react-spring/konva
@react-spring/native
@react-spring/three
@react-spring/web
@react-spring/zdog
```

## Browser support

The library comes as an es-module compiled for evergreen browsers with the following browserlist config: [`>1%, not dead, not ie 11, not op_mini all`](https://browserl.ist/?q=%3E1%25%2C+not+dead%2C+not+ie+11%2C+not+op_mini+all). If you need to support legacy targets or deal with targets that don't support modules, you can use the commonJS export by simply appending `.cjs` to your imports.

## Why springs and not durations

The principle you will be working with is called a `spring`, it _does not have a defined curve or a set duration_. In that it differs greatly from the animation you are probably used to. We think of animation in terms of time and curves, but that in itself causes most of the struggle we face when trying to make elements on the screen move naturally, because nothing in the real world moves like that.

<p align="middle">
  <img height="250" src="https://i.imgur.com/7CCH51r.gif" />
</p>

We are so used to time-based animation that we believe that struggle is normal, dealing with arbitrary curves, easings, time waterfalls, not to mention getting this all in sync. As Andy Matuschak (ex Apple UI-Kit developer) [expressed it once](https://twitter.com/andy_matuschak/status/566736015188963328): _Animation APIs parameterized by duration and curve are fundamentally opposed to continuous, fluid interactivity_.

Springs change that, animation becomes easy and approachable, everything you do looks and feels natural by default. For a detailed explanation watch the video below:

<YouTubeEmbed src="https://www.youtube.com/embed/1tavDv5hXpo?controls=0&amp;start=370" />

## People say

<TweetGrid />

## Used by

<GridUsedBy />
<br />

And [many others](https://github.com/pmndrs/react-spring/network/dependents) ...

## Funding

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

You can also support this project by becoming a sponsor. Your logo will show up here with a link to your website.

## Gold sponsors

<a href="https://aragon.org/">
  <img
    width="300"
    src="https://assets.website-files.com/602ced7da46f594dd6700e15/602cf7ea9fc1f41358f0ae27_5e99778310343ed2dfe89331_logo_big.svg"
  />
</a>

## Sponsors

<a href="https://opencollective.com/react-spring/sponsor/0/website" target="_blank">
  <img src="https://opencollective.com/react-spring/sponsor/0/avatar.svg" />
</a>
<a href="https://opencollective.com/react-spring/sponsor/1/website" target="_blank">
  <img src="https://opencollective.com/react-spring/sponsor/1/avatar.svg" />
</a>

## Backers

Thank you to all our backers! 🙏

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

### Contributors

This project exists thanks to all the people who contribute.

<a href="https://github.com/drcmda/react-spring/graphs/contributors">
  <img src="https://opencollective.com/react-spring/contributors.svg?width=890" />
</a>


The basic spring is [useSpring](/react-spring/hooks/use-spring), but the same concept applies to all animation primitives. Let's have a look...

```jsx
import { useSpring, animated } from 'react-spring'

function App() {
  const props = useSpring({ to: { opacity: 1 }, from: { opacity: 0 } })
  return <animated.div style={props}>I will fade in</animated.div>
}
```

### First, you fetch your imports

```jsx
import { useSpring, animated } from 'react-spring'
```

You need the animation-primitive itself, and a special factory called `animated`. This library animates outside React (for performance reasons). Your view has to know how to handle the animated props you pass to it. This is what `animated` is there for, it extends native elements to receive animated values.

### Next, define your spring

```jsx
const props = useSpring({ to: { opacity: 1 }, from: { opacity: 0 } })
```

A spring simply animates values from one state to another. Updates are accumulative, springs remember all the values you ever pass. You can use arbitrary names. There are a couple of reserved keywords like "from" (for base values). [You can learn about the api here](/react-spring/common/props). The received props are not static values! These props are self-updating, you cannot use them in regular divs and such.

### Finally, tie the animated values to your view

```jsx
return <animated.div style={props}>I will fade in</animated.div>
```

In the view part of your component you simply wire these props in. Make sure to extend the native element you want to animate using `animated`. If your target is the web then `animated` contains all valid html elements (divs, spans, svgs, etc). If you want to animate React components, styled-components, or elements on other platforms, then do this:

```jsx
// React components
const AnimatedDonut = animated(Donut)

// React-native
const AnimatedView = animated(View)

// styled-components, emotion, etc.
const AnimatedHeader = styled(animated.h1)`
  ...;
`
```

### Do not think of the values you pass as "styles" per se

Although you can use them as such.

<Demo name="title" />

Do with them whatever you like, animate attributes for instance,

<Demo name="svg" />

innerText,

<Demo name="innerText" />

scrollTop/scrollLeft,

<Demo name="scrolling" />

## Up-front interpolation

Springs take pretty much everything, they don't just handle numbers.

- Colors (names, rgb, rgba, hsl, hsla, gradients)
- Absolute lengths (cm, mm, in, px, pt, pc)
- Relative lengths (em, ex, ch, rem, vw, vh, vmin, vmax, %)
- Angles (deg, rad, grad, turn)
- Flex and grid units (fr, etc)
- All HTML attributes
- SVG paths (as long as the number of points matches, otherwise use [custom interpolation](https://codesandbox.io/embed/lwpkp46om))
- Arrays
- String patterns (transform, border, boxShadow, etc)
- Non-animatable string values (visibility, pointerEvents, etc)
- ScrollTop/scrollLeft

```jsx
const props = useSpring({
  vector: [0, 10, 30],
  display: 'block',
  padding: 20,
  background: 'linear-gradient(to right, #009fff, #ec2f4b)',
  transform: 'translate3d(0px,0,0) scale(1) rotateX(0deg)',
  boxShadow: '0px 10px 20px 0px rgba(0,0,0,0.4)',
  borderBottom: '10px solid #2D3747',
  shape: 'M20,20 L20,380 L380,380 L380,20 L20,20 Z',
  textShadow: '0px 5px 15px rgba(255,255,255,0.5)',
})
```

## Shorthand style props

**In the web version only,** you can avoid the boilerplate of using the `to`
function to combine multiple animated values into a `transform` string like you
had to do in v8.

Instead, you can try defining an animated value in the `style` object using one
of the following shorthand props:

- `x`, `y`, `z`
- `translate`, `translateX`, `translateY`, `translate3d`
- `rotate`, `rotateX`, `rotateY`, `rotate3d`
- `scale`, `scaleX`, `scaleY`, `scale3d`
- `skew`, `skewX`, `skewY`
- `matrix`, `matrix3d`

```jsx
const { x, y } = useSpring({ x: 0, y: 0 })

// v8
import { to } from 'react-spring'
const transform = to([x, y], (x, y) => `translate(${x}px, ${y}px)`)
return <a.div style={{ transform }} />

// v9
return <a.div style={{ x, y }} />
```

These shorthand props will be added to `@react-spring/native` in the future.
For now, they only exist in `@react-spring/web`. **Want them in native? Consider submitting a [PR](https://github.com/pmndrs/react-spring/issues/1408)**

## View interpolation

In cases where you need to clamp or extrapolate, each animated value can interpolate inside the view, which is a powerful tool to have. The interpolate function called `to` either takes a function or an object which forms a range. Interpolations can also form chains which allows you to route one calculation into another or reuse them. [Look into the shared-api](/react-spring/common/interpolation) for an object description.

You may wonder why you wouldn't always interpolate inside of the spring. View interpolation can be a little faster, and it takes up less space.

```jsx
import { useSpring, animated, to } from 'react-spring'

const { o, xyz, color } = useSpring({
  from: { o: 0, xyz: [0, 0, 0], color: 'red' },
  o: 1,
  xyz: [10, 20, 5],
  color: 'green',
})

return (
  <animated.div
    style={{
      // If you can, use plain animated values like always, ...
      // You would do that in all cases where values "just fit"
      color,
      // Unless you need to interpolate them
      background: o.to((o) => `rgba(210, 57, 77, ${o})`),
      // Which works with arrays as well
      transform: xyz.to((x, y, z) => `translate3d(${x}px, ${y}px, ${z}px)`),
      // If you want to combine multiple values use the "interpolate" helper
      border: to([o, color], (o, c) => `${o * 10}px solid ${c}`),
      // You can also form ranges, even chain multiple interpolations
      padding: o.to({ range: [0, 0.5, 1], output: [0, 0, 10] }).to((o) => `${o}%`),
      // Interpolating strings (like up-front) through ranges is allowed ...
      borderColor: o.to({ range: [0, 1], output: ['red', '#ffaabb'] }),
      // There's also a shortcut for plain, optionless ranges ...
      opacity: o.to([0.1, 0.2, 0.6, 1], [1, 0.1, 0.5, 1]),
    }}
  >
    {o.to((n) => n.toFixed(2)) /* innerText interpolation ... */}
  </animated.div>
)
```

## Additional notes

### Animating "auto"

Hooks differ from renderprops in that they don't know the view. Therefore handling "auto" is out of scope of the hooks api. This may sound like a regression, but consider that measuring auto with hooks is easier than ever before, and it makes patterns possible that were very hard to realize before, for [instance nesting auto content](https://twitter.com/0xca0a/status/1094683974679621633). Look for [react-resize-aware](https://github.com/FezVrasta/react-resize-aware), [react-measure](https://github.com/souporserious/react-measure), etc.

```jsx
const [bind, { height }] = useMeasure()

const props = useSpring({ height })

return (
  <animated.div style={{ overflow: 'hidden', ...props }}>
    <div {...bind}>content</div>
  </animated.div>
)
```

### Emulating css-keyframes

Sometimes you want to go through a series of states, like css keyframes, you can use interpolations for this.

```jsx
/*
0 % { transform: scale(1); }
25 % { transform: scale(.97); }
35 % { transform: scale(.9); }
45 % { transform: scale(1.1); }
55 % { transform: scale(.9); }
65 % { transform: scale(1.1); }
75 % { transform: scale(1.03); }
100 % { transform: scale(1); }
`*/

const props = useSpring({ x: state ? 1 : 0 })

return (
  <animated.div
    style={{
      transform: props.x
        .to({
          range: [0, 0.25, 0.35, 0.45, 0.55, 0.65, 0.75, 1],
          output: [1, 0.97, 0.9, 1.1, 0.9, 1.1, 1.03, 1],
        })
        .to((x) => `scale(${x})`),
    }}
  />
)
```

<Demo name="interpolation" onlyView />

### Dependency arrays

Every hook except `useChain` now supports a `deps` argument, which is an array exactly like what `useEffect` takes.

Whenever a dependency is changed, the update will be processed and thus the animation will be updated. But otherwise, updates are ignored when all dependencies are unchanged.

When a dependency array is passed, or the spring object is created with a function the `useSpring` and `useSprings` hooks each return an `api` object. For more information see the [`Imperatives & Refs`](/react-spring/common/imperatives-and-refs) section

```js
const [style, api] = useSpring({ x: 0, y: 0 }, [])
useEffect(() => {
  api.start({ x: 100, y: 100 })
}, [])
```

```js
const [style, api] = useSpring(() => ({ x: 0, y: 0 }))
useEffect(() => {
  api.start({ x: 100, y: 100 })
}, [])
```

Getting Started


## Overview

```jsx
useSpring({ from: { ... }, to: { ... }, delay: 100, onRest: () => ... })
```

All primitives inherit the following properties (though some of them may bring their own additionally):

| Property           | Type              | Description                                                                                                                                                              |
| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| from               | obj               | Base values, optional                                                                                                                                                    |
| to                 | obj/fn/array(obj) | Animates to ...                                                                                                                                                          |
| loop               | obj/fn/bool       | Looping settings, see [loop prop](#loop-prop) for more details                                                                                                           |
| delay              | number/fn         | Delay in ms before the animation starts. Also valid as a function for individual keys: key => delay                                                                      |
| immediate          | bool/fn           | Prevents animation if true. Also valid as a function for individual keys: key => immediate                                                                               |
| [config](#configs) | obj/fn            | Spring config (contains mass, tension, friction, etc). Also valid as a function for individual keys: key => config                                                       |
| reset              | bool              | The spring starts to animate from scratch (from -> to) if set true                                                                                                       |
| reverse            | bool              | "from" and "to" are switched if set true, this will only make sense in combination with the "reset" flag                                                                 |
| cancel             | bool/string/fn    | When `true`, the `cancel` prop stops the animation of every animated value owned by the `Controller` that receives it. See [cancel prop](/#cancel-prop) for more details |
| pause              | bool              | The `pause` prop literally freezes animations in time.                                                                                                                   |
| `events`           | fn                | A variety of event callbacks (see [events](#events) for more information)                                                                                                |

## Advanced Props

### Loop Prop

Use `loop: true` to repeat an animation.

```js render=true edit=true
function LoopTrue() {
  const styles = useSpring({
    loop: true,
    from: { rotateZ: 0 },
    to: { rotateZ: 180 },
  })

  return (
    <animated.div
      style={{
        width: 80,
        height: 80,
        backgroundColor: '#46e891',
        borderRadius: 16,
        ...styles,
      }}
    />
  )
}
```

### The `loop` function

Pass a function to be called after each loop. Return `true` to continue
looping, or `false` to stop.

```js render=true edit=true
function LoopFunction() {
  const n = useRef(0)
  const styles = useSpring({
    loop: () => 3 > n.current++,
    from: { x: 0 },
    to: { x: 100 },
  })

  return (
    <animated.div
      style={{
        width: 80,
        height: 80,
        backgroundColor: '#46e891',
        borderRadius: 16,
        ...styles,
      }}
    />
  )
}
```

The `loop` function can also return a `loop` object, which is described in the
next section. This is useful when you want to decide the next loop animation
right after the previous loop is finished.

### The `loop` object

Define a `loop` object to customize the loop animation separately from the
initial animation. It may contain any of the `useSpring` props. For example,
if `reverse: true` is used, the loop animation will reverse on each loop.

```js render=true edit=true
function LoopObject() {
  const styles = useSpring({
    loop: { reverse: true },
    from: { x: 0 },
    to: { x: 100 },
  })

  return (
    <animated.div
      style={{
        width: 80,
        height: 80,
        backgroundColor: '#46e891',
        borderRadius: 16,
        ...styles,
      }}
    />
  )
}
```

#### Inherited props

The `loop` object is always merged into a copy of the props object it was
defined in. The following example shows a loop animation that inherits its
`config` prop.

```js render=true edit=true
function InheritedProps() {
  const n = useRef(0)
  const styles = useSpring({
    from: { x: 0 },
    config: { duration: 1000 },
    loop: {
      x: 100,
    },
  })

  return (
    <animated.div
      style={{
        width: 80,
        height: 80,
        backgroundColor: '#46e891',
        borderRadius: 16,
        ...styles,
      }}
    />
  )
}
```

⚠️ Notice how the loop doesn't run more than once. That's because some props
are **never** inherited. These props include `default`, `reset`, and `reverse`.

**To loop the animation,** try adding `reset: true` to the `loop` prop in the above
example. Alternatively, you could add `from: { x: 0 }` to get the same effect.

Lastly, try adding `config: { friction: 5 }` to the `loop` object. This overrides
the inherited `config.duration` with a springy animation.

### Cancel Prop

When `true`, the `cancel` prop stops the animation of every animated value
owned by the `Controller` that receives it.

The following example never animates, because `cancel` is always true.

```js
useSpring({
  cancel: true,
  from: { x: 0 },
  to: { x: 100 },
})
```

Once the `cancel` prop turns from `true` to `false`, the declared animation
will resume or reset, depending on the given props.

#### Delayed updates

The `cancel` prop even prevents delayed updates. 😎

```jsx
const [style, animate] = useSpring(() => ({ x: 0 }))

// Pass this to an element.
const onClick = () => {
  animate({ x: 100, delay: 500 })

  // Prevent the previous update. 🤣
  animate({ cancel: true })
}
```

#### Specific keys

To cancel the animation of specific keys, you can pass a single key, an array of
keys, or a `(key: string) => boolean` function.

```js
// Using a single key
cancel: 'x',

// Using an array of keys
cancel: ['x', 'y'],

// Using a function
cancel: key => key !== 'x',
```

The `reset` and `immediate` props support these same types.

### Events

| Event name | Description                                              |
| ---------- | -------------------------------------------------------- |
| onStart    | Callback when a spring or key is about to be animated    |
| onChange   | Frame by frame callback                                  |
| onRest     | Callback when a spring or key comes to a stand-still     |
| onPause    | Callback when a spring or key is paused                  |
| onResume   | Callback when a spring or key is resumed                 |
| onDelayEnd | Callback when a spring or key has finished being delayed |
| onProps    | Callback when a spring or key's props have been updated  |

#### Events as functions

Events excluding `onDelayEnd` and `onProps` all have the same arguments passed to them:

```jsx
(result: AnimationResult, spring: Controller | SpringValue, item?: Item) => void
```

So lets break this down:

- `result` (1st arg) – is an [Animation Result](#animation-results), this is an object containing the values of your spring at time of calling.
- `spring` (2nd arg) – is either the `Controller` or `SpringValue` of the Animation Result, this called the event
- `item` (3rd arg) – this is only available when using the [useTransition](/react-spring/hooks/use-transition) hook or [Transition](/react-spring/components/transition) component.

> ⚠️ **warning** ⚠️ – Currently `onStart` is called after the first animation tick, this value is considered _dirty_

`onDelayEnd` & `onProps` have the following arguments passed:

```jsx
(props: SpringProps, spring: SpringValue) => void
```

- `props` (1st arg) – the props object of the spring (all merged from the new values just passed).
- `spring` (2nd arg) – the affected `SpringValue` object

#### Events as objects

Events like can also be defined on a per-key basis.

```jsx
useSpring({
  from: { x: 0, y: 0 },
  onRest: {
    x: () => console.log('x.onRest'),
    y: () => console.log('y.onRest'),
  },
})
```

#### Animation result

Some events receive an `AnimationResult` object as their first argument when called. It contains the following properties:

- `value: any` The current value when the animation ended.
- `finished?: boolean` Equals true when the animation finished before being stopped or cancelled.
- `cancelled?: boolean` Equals true when the animation was cancelled.

The promise returned by the ref API's `start` method is resolved with an `AnimationResult` object, as well as the `start` method of the `SpringValue`
and `Controller` classes.

## Default props

The `default` prop lets you set the default value of certain props defined in
the same update.

### Declarative updates

For the declarative API, this prop is `true` by default. In the following
example, the `onRest` handler is inherited by every update passed to `animate`,
except when a call has its own `onRest` prop defined.

```jsx
useSpring({
  to: async animate => { ... },
  onRest: () => { ... }
})
```

### Imperative updates

Imperative updates can use `default: true` to set default props. When an
async `to` prop is defined by an imperative update, it will inherit props from
the imperative update like this:

```jsx
useSpring({
  from: { x: 0 },
  to: async (animate) => {
    // The `config` prop below is inherited by
    // both objects in the `to` array.
    await animate({
      to: [{ x: 100 }, { x: 0 }],
      config: { tension: 100 },
    })
  },
})
```

Default props are inherited while an update is being processed by the internal
diffing algorithm within the `SpringValue#_merge` [method][merge1].

[merge1]: https://github.com/react-spring/react-spring/blob/09f9a8aa34e73321d701c815b643576affd82a1c/packages/core/src/SpringValue.ts#L562-L824

For example, both the `ref` prop and the `animate` function will inherit
the default props defined below (in the `useSpring` props function).

```jsx
const ref = useSpringRef()
const [{ x }, api] = useSpring(() => ({
  x: 0,
  onRest: () => { ... },
  ref,
}))

useEffect(async () => {
  // Animate to 100 with the ref API.
  await ref.current.start({ x: 100 })
  // Animate to 0 with the returned API.
  await api.start({ x: 0 })
}, [])
```

### Compatible props

In the last example, only the `onRest` prop is inherited, because only some
props can have a default value.

The following props can have default values:

- `cancel`
- `config`
- `immediate`
- `onChange`
- `onDelayEnd`
- `onProps`
- `onRest`
- `onStart`
- `pause`

### The `default` object

In addition to passing `default: true`, you can also pass an object instead.
Only the props defined in your `default` object will be saved for future updates.

In this example, we are setting `true` as the default value of `immediate`. This
affects all future animations owned by the `useSpring` call, whether or not they
are declarative or imperative.

```js
const { x } = useSpring({
  x: 0,
  default: { immediate: true },
})
useEffect(() => {
  // This will be immediate.
  x.start(100)
})
```


Props


Spring are configurable and can be tuned. If you want to adjust these settings, you should provide a `config` property to `useSpring`:

```js
useSpring({ config: { duration: 250 }, ... })
```

Since `v9` the `config` prop can now be partially updated:

```jsx
const { x } = useSpring({
  from: { x: 0 },
  config: { frequency: 1 },
})
useEffect(() => {
  x.start({ config: { velocity: 0 } })
  x.start({ config: { friction: 20 } })
}, [])
```

And we've added the following properties `frequency`, `dampening`, `round`, `bounce`, `progress` & `restVelocity`.

| Property     | Default   | Description                                                                                                                                                                                                       |
| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| mass         | 1         | spring mass                                                                                                                                                                                                       |
| tension      | 170       | spring energetic load                                                                                                                                                                                             |
| friction     | 26        | spring resistance                                                                                                                                                                                                 |
| clamp        | false     | when true, stops the spring once it overshoots its boundaries                                                                                                                                                     |
| precision    | 0.01      | precision                                                                                                                                                                                                         |
| velocity     | 0         | initial velocity                                                                                                                                                                                                  |
| easing       | t => t    | linear by default, you can use any easing you want, for instance d3-ease                                                                                                                                          |
| damping      | 1         | The damping ratio, which dictates how the spring slows down. Only works when `frequency` is defined. Defaults to `1`.                                                                                             |
| progress     | 0         | When used with `duration`, it decides how far into the easing function to start from. The duration itself is unaffected.                                                                                          |
| duration     | undefined | if > than 0 will switch to a duration-based animation instead of spring physics, value should be indicated in milliseconds (e.g. `duration: 250` for a duration of 250ms)                                         |
| decay        | undefined | `number` of decay rate. If passed `true` defaults to 0.998                                                                                                                                                        |
| frequency    | undefined | The natural frequency (in seconds), which dictates the number of bounces per second when no damping exists. When defined, `tension` is derived from this, and `friction` is derived from `tension` and `damping`. |
| round        | undefined | While animating, round to the nearest multiple of this number. The `from` and `to` values are never rounded, as well as any value passed to the `set` method of an animated value.                                |
| bounce       | undefined | When above zero, the spring will bounce instead of overshooting when exceeding its goal value.                                                                                                                    |
| restVelocity | undefined | The smallest velocity before the animation is considered to be "not moving". When undefined, `precision` is used instead.                                                                                         |

<Codesandbox id="x1vjb" />

## Presets

There are also a couple of generic presets that will cover some common ground.

```jsx
import { ..., config } from 'react-spring'

useSpring({ ..., config: config.default })
```

| Property        | Value                                    |
| --------------- | ---------------------------------------- |
| config.default  | { mass: 1, tension: 170, friction: 26 }  |
| config.gentle   | { mass: 1, tension: 120, friction: 14 }  |
| config.wobbly   | { mass: 1, tension: 180, friction: 12 }  |
| config.stiff    | { mass: 1, tension: 210, friction: 20 }  |
| config.slow     | { mass: 1, tension: 280, friction: 60 }  |
| config.molasses | { mass: 1, tension: 280, friction: 120 } |

<Codesandbox id="kdv7r" />


Configs


While this section uses examples using `hooks` using `createRef` inside a class component will give you the same result.

## Imperative API

> a.k.a Why did you get rid of `set`?

The old api looked something like this:

```js
const [props, set, stop] = useSpring(() => ({ opacity: 1 }))

// Update spring with new props
set({ opacity: toggle ? 1 : 0 })
```

And while this was really good, it's not the best API, having the imperative API returned from the spring stops you from digging for the correct function. It makes extensibility easier too if we add more api methods.

However, if you're really set on loving the old `set`, from `9.1.0` we have aliased the second arg to call `api.start` which is the v9 equivalent of `set`. This will give you a depreciation notice:

<Demo name="backwardsCompatability" />

### The `from` prop

The `from` prop now behaves differently in imperative updates. When defined, it implies the `reset` prop is true. Previously, the `from` prop would not affect the animation unless `reset: true` was explicitly defined.

To prevent this behavior, you can define `reset: false`.

```jsx
const { x } = useSpring({ x: 0 })
useEffect(() => {
  // This animates as expected, from 100 to 0.
  x.start({ from: 100, to: 0 })
})
```

## API methods

The api object, set to a SpringRef or returned as the second arg of an array returned from a spring has the following methods:

```ts
const api = {
    // start your animation optionally giving new props to merge e.g. a `to` object
    start: (props) => AnimationResult,
    // sets the spring to specific passed values
    set: (props) => void,
    // Add props to each controller's update queue.
    update: (props) => this,
    // Add a controller to the springRef
    add: (ctrl) => this,
    // Delete a controller from the springRef
    delete: (ctrl) => this,
    // Cancel some or all animations depending on the keys passed, no keys will cancel all.
    stop: (cancel, keys) => this,
    // pause specific spring keys of the spring function
    pause: (keys) => this
    // resume specific spring keys of the spring function
    resume: (keys) => this
}
```

## Using Refs

Introducing `useSpringRef`! The library version of `useRef` to be used instead of `useRef` in the following situations:

```jsx
const springRef = useSpringRef()

const { size, ...rest } = useSpring({
  ref: springApi,
  config: config.stiff,
  from: { size: '20%', background: 'hotpink' },
  to: {
    size: '100%',
    background: 'white',
  },
})

useEffect(() => {
  // this will give you access to the same API documented above
  console.log(springRef.current)
}, [])
```

Internally, the ref has the `Controller` added to it using the `add` method. Therefore, using `useRef` will throw an error.
This is especially helpful when using `useChain`.


Imperatives & Refs


🚧 We'd love to add some examples to this, consider submitting a [PR](https://github.com/pmndrs/react-spring) 🚧

`value.to` either takes an object of the following shape:

| Value            | default   | Description                                      |
| ---------------- | --------- | ------------------------------------------------ |
| extrapolateLeft  | extend    | Left extrapolate. Can be: identity/clamp/extend  |
| extrapolateRight | extend    | Right extrapolate. Can be: identity/clamp/extend |
| extrapolate      | extend    | Shortcut to set left and right-extrapolate       |
| range            | [0,1]     | Array of input ranges                            |
| output           | undefined | Array of mapped output ranges                    |
| map              | undefined | Value filter applied to input value              |

A range shortcut: `value.to([...inputRange], [...outputRange])`

Or a function: `value.to(v => ...)`


Interpolations


## Overview

```js
import { useChain, animated } from 'react-spring'
```

Set the execution order of previously defined animation-hooks, where one animation starts after the other in sequence. You need to collect refs off the animations you want to chain, which blocks the animation from starting on its own. The order can be changed in subsequent render passes.

```jsx
// Build a spring and catch its ref
const springRef = useSpringRef()
const props = useSpring({ ...values, ref: springRef })
// Build a transition and catch its ref
const transitionRef = useSpringRef()
const transitions = useTransition({ ...values, ref: transitionRef })
// First run the spring, when it concludes run the transition
useChain([springRef, transitionRef])
// Use the animated props like always
return (
  <animated.div style={props}>
    {transitions((styles) => (
      <animated.div style={styles} />
    ))}
  </animated.div>
)
```

You can optionally define timeSteps and a timeFrame (which defaults to a second). timeSteps is just an array with offsets between 0-1 that correspend to beginning and the end of the timeFrame.

```jsx
// The spring will start right away: 0.0 * 1000ms = 0ms
// The transition will start after: 0.5 * 1000ms (the timeFrame default) = 500ms
useChain([springRef, transitionRef], [0, 0.5] /*1000*/)
```

## Demos

<DemoGrid>
  <Demo title="Chain" url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/chain" />
</DemoGrid>


useChain


## Overview

```js
import { useSpring, animated } from 'react-spring'
```

Turns values into animated-values.

### Either: overwrite values to change the animation

If you re-render the component with changed props, the animation will update.

```jsx
const styles = useSpring({ opacity: toggle ? 1 : 0 })
```

### Or: pass a function that returns values, and update using the api

You will get an API object back. It will not cause the component to render like an overwrite would (the animation still executes of course). Handling updates like this is useful for fast-occurring updates, and you should generally prefer it as it's more powerful. Further documentation can be found in [Imperatives & Refs](/react-spring/common/imperatives-and-refs#api-methods)

```jsx
const [styles, api] = useSpring(() => ({ opacity: 1 }))

// Update spring with new props
api.start({ opacity: toggle ? 1 : 0 })
// Stop animation
api.stop()
```

### Finally: distribute animated props among the view

The return value is an object containing animated props.

```jsx
return <animated.div style={styles}>i will fade</animated.div>
```

## Properties

All properties documented in the [common props](/react-spring/common/props) apply.

## Additional notes

### To-prop shortcut

Any property that useSpring does not recognize will be combined into "to", for instance `opacity: 1` will become `to: { opacity: 1 }`.

```jsx
// This ...
const props = useSpring({ opacity: 1, color: 'red' })
// is a shortcut for this ...
const props = useSpring({ to: { opacity: 1, color: 'red' } })
```

### Async chains/scripts

The `to` prop also allows you to 1. script your animation, or 2. chain multiple animations together. Since these animations will execute asynchronously, make sure to provide a `from` property for base values (otherwise, props will be empty).

#### This is how you create a script

```jsx
function AsyncExample() {
  const styles = useSpring({
    to: async (next, cancel) => {
      await next({ opacity: 1, color: '#ffaaee' })
      await next({ opacity: 0, color: 'rgb(14,26,19)' })
    },
    from: { opacity: 0, color: 'red' },
  })
  // ...
  return <animated.div style={styles}>I will fade in and out</animated.div>
}
```

#### And this is how you create a chain

<Demo name="chain-use-spring" />

When using an async `to` function inside a component that renders frequently,
you'll need to memoize your `to` function to prevent an unintended restart.

One solution is to use the `useCallback` hook.

```jsx
useSpring({
  to: useCallback(async next => { ... }, []),
})
```

Another solution is to pass a props function.

```jsx
useSpring(() => ({
  to: async next => { ... },
}))
```

## Demos

<DemoGrid>
  <Demo
    title="Animating Auto"
    url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/animating-auto"
  />
  <Demo title="Card" url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/card" />
  <Demo
    title="CSS Keyframes"
    url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/css-keyframes"
  />
  <Demo
    title="Flip Card"
    url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/flip-card"
  />
  <Demo title="Slide" url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/slide" />
  <Demo
    url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/svg-filter"
    title="SVG Filter"
  />
  <Demo title="Tree" url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/tree" />
</DemoGrid>


useSpring


## Overview

```js
import { useSprings, animated } from 'react-spring'
```

Creates multiple springs, each with its own config. Use it for static lists, etc.

### Either: overwrite values to change the animation

If you re-render the component with changed props, the animation will update.

```jsx
const springs = useSprings(
  number,
  items.map((item) => ({ opacity: item.opacity }))
)
```

### Or: pass a function that returns values, and update using the API

You will get an updater function back. It will not cause the component to render like an overwrite would (still the animation executes of course). Handling updates like this is useful for fast-occurring updates, but you should generally prefer it. Optionally there's also a stop function as a third argument.

```jsx
const [springs, api] = useSprings(number, (index) => ({ opacity: 1 }))

// Update springs with new props
api.start((index) => ({ opacity: 0 }))
// Stop all springs
api.stop()
```

### Finally: distribute animated props among the view

The return value is an array containing animated props.

```jsx
return springs.map((styles) => <animated.div style={styles} />)
```

## Properties

All properties documented in the [common props](/react-spring/common/props) apply.

## Demos

<DemoGrid>
  <Demo
    title="Card Stack"
    url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/cards-stack"
  />
  <Demo
    title="Draggable List"
    url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/draggable-list"
  />
  <Demo
    title="Viewpager"
    url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/viewpager"
  />
</DemoGrid>


useSprings


## Overview

```js
import { useTrail, animated } from 'react-spring'
```

Creates multiple springs with a single config, each spring will follow the previous one. Use it for staggered animations.

### Either: overwrite values to change the animation

If you re-render the component with changed props, the animation will update.

```jsx
const trail = useTrail(amount, { opacity: 1 })
```

### Or: pass a function that returns values, and update using "set"

You will get an API object back. It will not cause the component to render like an overwrite would (the animation still executes of course). Handling updates like this is useful for fast-occurring updates, and you should generally prefer it as it's more powerful. Further documentation can be found in [Imperatives & Refs](/react-spring/common/imperatives-and-refs#api-methods)

```jsx
const [trail, api] = useTrail(amount, () => ({ opacity: 1 }))

// Update trail
api.start({ opacity: 0 })
// Stop trail
api.stop()
```

### Finally: distribute animated props among the view

The return value is an array containing animated props.

```jsx
return trail.map((styles) => <animated.div style={styles} />)
```

## Properties

All properties of the [shared-api](/react-spring/common/props) apply.

## Demos

<DemoGrid>
  <Demo
    title="Goo Blobs"
    url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/goo-blobs"
  />
  <Demo title="Trail" url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/trail" />
</DemoGrid>


useTrail

## Overview

```js
import { useTransition, animated } from 'react-spring'
```

An animated TransitionGroup. Feed it your items and lifecycles. Whenever items are added or removed, it will animate these changes.

### You can transition arrays

<Demo name="chain-use-transition" />

### Toggle between components

<Demo name="components-use-transition" />

### Mount/Unmount single-component reveals

<Demo name="mount-use-transition" />

The `transition` function accepts a callback that receives four arguments: the animated values,
the item, the `Transition` object, and the sibling position.

It returns a React fragment containing every element returned by your
callback. As you might assume, elements in the middle of their `leave`
animation need to remain mounted.

All elements in the fragment are guaranteed to have a `key` prop, whether or
not you define one explicitly. Unkeyed elements will use the `ctrl.id` from
their `Transition` object.

For every unique item key, there exists a `Transition` object. The only time
you have access to a `Transition` object is when it's passed as the 3rd argument
of your transition callback.

```js
// The `t` argument is a Transition object.
// The `i` argument is the sibling position.
const elems = transition((style, item, t, i) => <a.div style={style}>{t.phase}</a.div>)
```

## Properties

All properties of the [shared-api](/react-spring/common/props) apply.

| Property | Type              | Description                                                                                                                                                                   |
| -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| initial  | obj/fn            | Initial (first time) base values, optional (can be null)                                                                                                                      |
| from     | obj/fn            | Base values, optional                                                                                                                                                         |
| enter    | obj/fn/array(obj) | Styles apply for entering elements                                                                                                                                            |
| update   | obj/fn/array(obj) | Styles apply for updating elements (you can update the hook itself with new values)                                                                                           |
| leave    | obj/fn/array(obj) | Styles apply for leaving elements                                                                                                                                             |
| trail    | number            | Delay in ms before the animation starts, adds up for each enter/update and leave                                                                                              |
| reset    | bool/fn           | Prefers the `initial` prop over the `from` prop.                                                                                                                              |
| keys     | array/function    | see [keys](/react-spring/hooks/use-transition#keys) for more information                                                                                                      |
| key      | single item       | only use if you're passing a single item to `useTransition` see [keys](/react-spring/hooks/use-transition#keys) for more information                                          |
| expires  | bool/number       | lets you control when removed items are unmounted (after their `leave` animation has finished) see [expires](/react-spring/hooks/use-transition#expires) for more information |
| sort     | fn                | useful shortcut for slicing and sorting your items array before passing it to the `useTransition` hook                                                                        |

### Keys

Every `Transition` object has a unique key that identifies it. You have the
option of defining explicit keys or letting the "item" (the value represented
by the `Transition` object) be its own key.

To define explicit keys, you must define the `keys` prop in your `useTransition`
props. For example, when using an items array, the new `keys` prop can be:

- an array of keys
- or a mapping function that returns a key for any item given to it.

```js
useTransition(items, {
  // Using a function
  keys: (item) => item.key,
  // Using an array created by lodash.map
  keys: _.map(items, 'key'),
})
```

⚠️ You **must** use explicit keys for any item that is an immutable object.

Using explicit keys for mutable objects is unnecessary. 🥳

If you're passing a single item to `useTransition`, you have the option of
passing a single key as the `key` prop.

```js
useTransition(item, {
  key: item.key,
})
```

### Expires

The `expires` prop lets you control when removed items are unmounted (after
their `leave` animation has finished). By default, unmounting is postponed
until the next render or until all transitions are resting.

When `true` or `<= 0`, the default behavior is used.

When `false`, items are never unmounted.

When `> 0`, this prop is used in a `setTimeout` call that forces a
rerender if the component that called `useTransition` doesn't rerender
on its own after an item's `leave` animation is finished.

Finally, the `expires` prop can be a function that receives an item and returns any of
the values mentioned above.

### Sort

The `sort` prop is a function that takes two items, returns `-1` when
the 1st item should appear first, and returns `1` when the 2nd item should.

It's a useful shortcut for slicing and sorting your items array before passing
it to the `useTransition` hook.

```js
// v8
useTransition(items.slice().sort(props.sort), null, props)

// v9
useTransition(items, {
  sort: (a, b) => { ... },
  ...props
})
```

## Additional notes

### Multi-stage transitions

The initial/from/enter/update/leave lifecycles can be objects, arrays or functions. When you provide a function you have access to individual items. The function is allowed to return plain objects, or either an array or a function for multi-stage transitions. When you provide a plain array you also can form a basic multi-stage transition (without access to the item).

```jsx
useTransition(items, {
  enter: (item) => [{ opacity: item.opacity, height: item.height }, { life: '100%' }],
  leave: (item) => async (next, cancel) => {
    await next({ life: '0%' })
    await next({ opacity: 0 })
    await next({ height: 0 })
  },
  from: { life: '0%', opacity: 0, height: 0 },
})
```

### Transitioning between routes

```jsx
const location = useLocation()
const transitions = useTransition(location, { ... })
return transitions((props, item) => (
  <animated.div style={props}>
    <Switch location={item}>
      <Route path="/a" component={A} />
      <Route path="/b" component={B} />
      <Route path="/c" component={C} />
    </Switch>
  </animated.div>
))
```



## Demos

<DemoGrid>
  <Demo
    title="Image Fade"
    url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/image-fade"
  />
  <Demo
    title="List Reordering"
    url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/list-reordering"
  />
  <Demo title="Masonry" url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/masonry" />
  <Demo
    title="Multistage Transition"
    url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/multistage-transition"
  />
  <Demo
    title="Notification Hub"
    url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/notification-hub"
  />
  <Demo
    title="Simple Transition"
    url="github/pmndrs/react-spring/tree/master/demo/src/sandboxes/simple-transition"
  />
</DemoGrid>

useTransition


## Overview

```js
import { Parallax } from 'react-spring'
```

> 🚧 Oh no, that's embarrassing. It looks like we don't have the knowledge to fill this page in. If you think you do, please consider submitting a [PR](https://github.com/pmndrs/website) 🚧


Parallax


Modify animations within the given `children`, but only the animations created
by the hook API (eg: `useSpring`) or renderprops API (eg: `<Spring>`) are affected.
Animations created with `new SpringValue()` or `new Controller()` are unaffected.

```jsx
<SpringContext cancel={true}>
  <App />
</SpringContext>
```

The following props are supported:

- `cancel?: boolean`
- `config?: SpringConfig` (see [configs](/react-spring/common/configs) for more information)
- `immediate?: boolean`
- `pause?: boolean`

The `SpringContext` component can be used anywhere.

The most common use case is pausing or finishing animations on a page while it
is temporarily invisible to the user. For example, the user may navigate away
from a modal with animated content that stays mounted when hidden.

### Nested context

Descendants of a `SpringContext` component can use `SpringContext` to selectively
override any props forced by another `SpringContext`.

In the example below, only `Page2` can play its animations. Pretend this element
tree is rendered more dynamically, and this code is a static representation.

```jsx
<SpringContext pause={true}>
  <Page1 />
  <SpringContext pause={false}>
    <Page2 />
  </SpringContext>
  <Page3 />
</SpringContext>
```

Every nested `SpringContext` inherits the values of the nearest `SpringContext`
ancestor.


SpringContext


## Overview

```js
import { Spring, animated } from 'react-spring'
```

Turns values into animated-values.

### Either: overwrite values to change the animation

If you re-render the component with changed props, the animation will update.

```jsx
<Spring opacity={toggle ? 1 : 0}>
  {styles => ...}
</Spring>
```

### Or: pass a SpringRef and update using the api

It will not cause the component to render like an overwrite would (the animation still executes of course). Handling updates like this is useful for fast-occurring updates, and you should generally prefer it as it's more powerful. Further documentation can be found in [Imperatives & Refs](/react-spring/common/imperatives-and-refs#api-methods)

```jsx
const springRef = new SpringRef()

springRef.start({
  to: {
    opacity: 1
  }
})

<Spring ref={springRef} from={{ opacity: 0 }}>
  {styles => ...}
</SpringRef>
```

### Finally: distribute animated props among the view

The child of `Spring` is a render prop function.

```jsx
;(styles) => <animated.div style={styles}>i will fade</animated.div>
```

## Properties

All properties documented in the [common props](/react-spring/common/props) apply.

## Additional notes

### To-prop shortcut

Any property that Spring does not recognize will be combined into "to", for instance `opacity: 1` will become `to: { opacity: 1 }`.

```jsx
// This ...
<Spring opacity={1} color={'red'} />
// is a shortcut for this ...
<Spring to={{ opacity: 1, color: 'red' }} />
```

### Async chains/scripts

The `to` prop also allows you to 1. script your animation, or 2. chain multiple animations together. Since these animations will execute asynchronously, make sure to provide a `from` property for base values (otherwise, props will be empty).

#### This is how you create a script

```jsx
class AsyncExample extends PureComponent {
  handleAsyncTo = async (next, cancel) => {
    await next({ opacity: 1, color: '#ffaaee' })
    await next({ opacity: 0, color: 'rgb(14,26,19)' })
  }

  render() {
    // ...
    return (
      <Spring to={handleAsyncTo} from={{ opacity: 0, color: 'red' }}>
        {(styles) => <animated.div style={styles}>I will fade in and out</animated.div>}
      </Spring>
    )
  }
}
```

#### And this is how you create a chain

<Demo name="chain" />


Spring


## Overview

```js
import { Trail, animated } from 'react-spring'
```

Creates multiple springs with a single config, each spring will follow the previous one. Use it for staggered animations.

### Either: overwrite values to change the animation

If you re-render the component with changed props, the animation will update.

```jsx
<Trail items={items} opacity={1}>
    {...}
</Trail>
```

### Or: pass a function that returns values, and update using "set"

You will get an API object back. It will not cause the component to render like an overwrite would (the animation still executes of course). Handling updates like this is useful for fast-occurring updates, and you should generally prefer it as it's more powerful. Further documentation can be found in [Imperatives & Refs](/react-spring/common/imperatives-and-refs#api-methods)

```jsx
const springRef = new SpringRef()

<Trail ref={springRef} items={items} opacity={1}>
    {...}
</Trail>

// Update trail
springRef.start({ opacity: 0 })
// Stop trail
springRef.stop()
```

### Finally: distribute animated props among the view

The return value is an array containing animated props.

```jsx
;(item) => (styles) => <animated.div style={styles}>{item.text}</animated.div>
```

## Properties

All properties of the [shared-api](/react-spring/common/props) apply.


Trail


## Overview

```js
import { Transition, animated } from 'react-spring'
```

An animated TransitionGroup. Feed it your items and lifecycles. Whenever items are added or removed, it will animate these changes.

### You can transition arrays

<Demo name="transition-array" />

### Toggle between components

<Demo name="transition-component" />

### Mount/Unmount single-component reveals

<Demo name="mount-component" />

The `transition` function accepts a callback that receives four arguments: the animated values,
the item, the `Transition` object, and the sibling position.

It returns a React fragment containing every element returned by your
callback. As you might assume, elements in the middle of their `leave`
animation need to remain mounted.

All elements in the fragment are guaranteed to have a `key` prop, whether or
not you define one explicitly. Unkeyed elements will use the `ctrl.id` from
their `Transition` object.

For every unique item key, there exists a `Transition` object. The only time
you have access to a `Transition` object is when it's passed as the 3rd argument
of your transition callback.

```js
// The `t` argument is a Transition object.
// The `i` argument is the sibling position.
const elems = transition((style, item, t, i) => <a.div style={style}>{t.phase}</a.div>)
```

## Properties

All properties of the [shared-api](/react-spring/common/props) apply.

| Property | Type              | Description                                                                                                                                                                   |
| -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| initial  | obj/fn            | Initial (first time) base values, optional (can be null)                                                                                                                      |
| from     | obj/fn            | Base values, optional                                                                                                                                                         |
| enter    | obj/fn/array(obj) | Styles apply for entering elements                                                                                                                                            |
| update   | obj/fn/array(obj) | Styles apply for updating elements (you can update the hook itself with new values)                                                                                           |
| leave    | obj/fn/array(obj) | Styles apply for leaving elements                                                                                                                                             |
| trail    | number            | Delay in ms before the animation starts, adds up for each enter/update and leave                                                                                              |
| reset    | bool/fn           | Prefers the `initial` prop over the `from` prop.                                                                                                                              |
| keys     | array/function    | see [keys](/react-spring/hooks/use-transition#keys) for more information                                                                                                      |
| key      | single item       | only use if you're passing a single item to `useTransition` see [keys](/react-spring/hooks/use-transition#keys) for more information                                          |
| expires  | bool/number       | lets you control when removed items are unmounted (after their `leave` animation has finished) see [expires](/react-spring/hooks/use-transition#expires) for more information |
| sort     | fn                | useful shortcut for slicing and sorting your items array before passing it to the `useTransition` hook                                                                        |

### Keys

Every `Transition` object has a unique key that identifies it. You have the
option of defining explicit keys or letting the "item" (the value represented
by the `Transition` object) be its own key.

To define explicit keys, you must define the `keys` prop in your `useTransition`
props. For example, when using an items array, the new `keys` prop can be:

- an array of keys
- or a mapping function that returns a key for any item given to it.

```js
useTransition(items, {
  // Using a function
  keys: (item) => item.key,
  // Using an array created by lodash.map
  keys: _.map(items, 'key'),
})
```

⚠️ You **must** use explicit keys for any item that is an immutable object.

Using explicit keys for mutable objects is unnecessary. 🥳

If you're passing a single item to `useTransition`, you have the option of
passing a single key as the `key` prop.

```js
useTransition(item, {
  key: item.key,
})
```

### Expires

The `expires` prop lets you control when removed items are unmounted (after
their `leave` animation has finished). By default, unmounting is postponed
until the next render or until all transitions are resting.

When `true` or `<= 0`, the default behavior is used.

When `false`, items are never unmounted.

When `> 0`, this prop is used in a `setTimeout` call that forces a
rerender if the component that called `useTransition` doesn't rerender
on its own after an item's `leave` animation is finished.

Finally, the `expires` prop can be a function that receives an item and returns any of
the values mentioned above.

### Sort

The `sort` prop is a function that takes two items, returns `-1` when
the 1st item should appear first, and returns `1` when the 2nd item should.

It's a useful shortcut for slicing and sorting your items array before passing
it to the `useTransition` hook.

```js
// v8
useTransition(items.slice().sort(props.sort), null, props)

// v9
useTransition(items, {
  sort: (a, b) => { ... },
  ...props
})
```

## Additional notes

### Multi-stage transitions

The initial/from/enter/update/leave lifecycles can be objects, arrays or functions. When you provide a function you have access to individual items. The function is allowed to return plain objects, or either an array or a function for multi-stage transitions. When you provide a plain array you also can form a basic multi-stage transition (without access to the item).

```jsx
useTransition(items, {
  enter: (item) => [{ opacity: item.opacity, height: item.height }, { life: '100%' }],
  leave: (item) => async (next, cancel) => {
    await next({ life: '0%' })
    await next({ opacity: 0 })
    await next({ height: 0 })
  },
  from: { life: '0%', opacity: 0, height: 0 },
})
```

### Transitioning between routes

```jsx
const location = useLocation()
const transitions = useTransition(location, { ... })
return transitions((props, item) => (
  <animated.div style={props}>
    <Switch location={item}>
      <Route path="/a" component={A} />
      <Route path="/b" component={B} />
      <Route path="/c" component={C} />
    </Switch>
  </animated.div>
))
```


Transition


## Overview

The `Controller` is react-spring's heart. All primitives use it internally (including hooks). If you dislike render-props, and maybe hooks are too radical for you, then perhaps this is what you are looking for as it gives you full manual control without having to worry about loose-end animation handles. The api is very similar to the `useSpring` hook.

```jsx
import { Controller, animated } from 'react-spring'

class Test extends React.Component {
  state = { show: true }
  animations = new Controller({ opacity: 0 })

  toggle = () => this.setState((state) => ({ show: !state.show }))

  render() {
    const props = this.animations.update({ opacity: this.state.show ? 1 : 0 })
    return (
      <>
        <button onClick={this.toggle}>click</button>
        <animated.div style={props}>I will fade</animated.div>
      </>
    )
  }
}
```

## Methods

### `each((spring, key) => void): void`

Call a function once per spring value.

```js
controller.each((spring, key) => (key === 'opacity' ? spring.set(1) : spring.set(0)))
```

### `get(): T`

Get the current values of our springs.

```js
const springValues = controller.get()
```

### `pause(): this`

Freeze the active animation in time.

```js
contoller.pause()
```

### `pause(keys): this`

Freezes some of the spring animations in time.

```js
contoller.pause(['opacity', 'color'])
```

### `resume(): this`

Resumes the active animation.

```js
contoller.resume()
```

### `resume(keys): this`

Resumes some of the paused spring animations.

```js
contoller.resume(['opacity', 'color'])
```

### `set(values): void`

Set the current values without animating.

```js
contoller.set({ opacity: 1, color: 0x0000ff })
```

### `start(): Promise<AnimationResult>`

Start the queued animations for every spring, and resolve the returned promise once all queued animations have finished or been cancelled.

```js
controller.start()
```

### `start(props): Promise<AnimationResult>`

When you pass a queue (instead of nothing), that queue is used instead of the queued animations added with the `update` method, which are left alone.

```js
controller.start({ opacity: 1, color: 0x0000ff })
```

### `stop(): this`

Stop all animations.

```js
contoller.stop()
```

### `stop(keys): this`

Stop animations for the given keys.

```js
contoller.stop(['opacity', 'color'])
```

### `stop(cancel, keys): this`

Cancel animations for the given keys.

```js
contoller.stop(true, ['opacity', 'color'])
```

### `update(props): this`

Push an update onto the queue of each value.

```js
contoller.update({ opacity: 1, color: 0x0000ff })
```

## Properties

### `get idle(): boolean`

Returns `true` when both:

- the current phase is _anything but_ `ACTIVE`
- no async `to` prop is active

Put simply, it's `true` when not animating.

### `get item(): any`

Returns the item the `Controller` is associated with. You probably don't need to use this much.

This is used only in the [`useTransition`](/react-spring/hooks/use-transition) hook & [`Transition`](/react-spring/components/transition) render-props component.

### `set item(item): void`

Sets the item the `Controller` is associated with. You probably don't need to use this much.

This is used only in the [`useTransition`](/react-spring/hooks/use-transition) hook & [`Transition`](/react-spring/components/transition) render-props component.

### `queue: SpringUpdate<T>[]`

The queue of pending updates.

Call `.start()` to flush the queue.

### `ref?: SpringRef<T>`

The injected ref. When defined, render-based updates are pushed onto the `queue` instead of being auto-started.

### `springs: SpringValues<T>`

The animated values


Controller


Imperative APIs are a great way of animating in response to events, without
the need for component state (ie: render-based updates). In this sense, the
`SpringValue` class is a welcome addition to `react-spring`.

## Intro

Create an animated value. Any type is valid, but only certain types are
actually animated.

The `props` argument can be either..

- a `to` value
- or a set of [`useSpring`](/react-spring/hooks/use-spring) props.

Types that cannot be animated are basically `immediate: true` animations.
Such types include: a `boolean`, a `display` string like `"none"`, etc.

The animatable types are:

- `number`

```js
new SpringValue(0)
```

- `string` with numbers

```js
new SpringValue('0px 10px')
new SpringValue('rgba(0, 0, 255, 1)')
```

- named colors

```js
new SpringValue('red')
```

- and arrays of the preceding types

```js
new SpringValue([0, '1em'])
```

## Methods

### `get(): T`

Get the current value.

```js
const value = spring.get()
```

### `set(value): this`

Set the current value, replace the `goal` value, and stop animating.

```js
spring.set(1)
```

### `update(props): this`

Add an update to the `queue` array. All updates in the `queue` are
applied at the same time.

```js
const delays = [0, 100, 300]
for (const delay of delays) {
  spring.update({ x: delay })
}
spring.start()
```

⚠️ This method may be deprecated soon.

### `start(): Promise`

Process the `queue` array and replace it with an empty array.

The returned `Promise` resolves after every animation triggered by
the `queue` array has either finished or been cancelled.

```js
await spring.start()
```

The awaited value is an [`AnimationResult`](/react-spring/common/props#animation-result) object.

### `start(props): Promise`

Process the given `props` object.

The returned promise is resolved after the animation is finished or cancelled.
If a `start` call triggers no animation, the promise resolves immediately.

```js
await spring.start({ from: 0, to: 1 })
```

### `start(queue): Promise`

Process the given array of updates.

The returned promise resolves to an [`AnimationResult`](/react-spring/common/props#animation-result) object whose:

- `finished` property is only `true` when every animation triggered by
  the `queue` was finished before being stopped or cancelled.

- `cancelled` property is only `false` when all updates in the `queue` were
  never cancelled.

```js
// prettier-ignore
await spring.start([
  { from: 0 },
  { to: 10 },
  { to: 20, delay: 1000 },
])
```

### `finish(): this`

Jump to the goal value immediately.

The `onStart` prop is called whenever `finish` is called before the first
frame. The `onRest` prop is called with `finished: true` as expected.

```js
spring.finish()
```

### `finish(value): this`

Jump to the given value immediately, and call the `onStart` and `onRest`
props the same way `.finish()` does.

```js
spring.finish(100)
```

Fluid values (eg: other `SpringValue` objects) can also be passed.

### `stop(): this`

Stop animating and cancel any delayed updates.

The `goal` value is replaced with the current value.

```js
spring.stop()
```

### `reset(): this`

Restart the animation using its cached `from` and `to` values.

```js
spring.reset()
```

Equivalent to a `.start({ reset: true })` call.

### `advance(dt: number): boolean`

Advance the current animation by the given `dt` (in milliseconds).

_You will probably never call this._

```js
// Advance a single frame.
spring.advance(1000 / 60)
```

### `is(phase: string): void`

Check for the given phase.

```jsx
if (spring.is('PAUSED')) {
  return
}
```

Valid phases include:

- `CREATED` The spring has never animated since being created.
- `IDLE` The spring is done animating.
- `ACTIVE` The spring is animating.
- `PAUSED` The spring was animating but is now paused.
- `DISPOSED` The spring can no longer animate.

## Properties

### `key?: string`

The name given to the `SpringValue` object by its owner.

For `Controller` objects, the `key` of each `SpringValue` is the property name
from either the `to` or `from` object prop.

When defined, the `to` prop can be an object with this `key` defined as
a property.

```js
spring.key = 'foo'
spring.start({ to: { foo: '180deg' } })
```

### `get idle(): boolean`

Returns `true` when both:

- the current phase is _anything but_ `ACTIVE`
- no async `to` prop is active

Put simply, it's `true` when not animating.

### `get goal(): T`

The end value of the current animation.

### `get velocity(): number | number[]`

The velocity of the current animation.

### `animation: Animation`

The animation descriptor.

### `queue?: SpringUpdate<T>[]`

The queue of pending updates.

Call `.start()` to flush the queue.


SpringValue


## Why is building accessible animations important?

react-spring makes building animations simple, but it is important to ensure your site/app is still accessible for those who don't enjoy animations.

Vestibular dysfunction, a balance disorder of the inner ear, is surprisingly common among US adults. [A study](https://www.ncbi.nlm.nih.gov/pubmed/19468085) from the early 2000's found that approximately 69 million Americans had vestibular dysfunction which results in vertigo, nausea, migraines and hearing loss. Many people affected by vestibular dysfunction will choose to set the "Reduce motion" setting in their OS. In macOS it's found in the accessibility settings.

<p align="middle">
  <img
    alt="macOS accessibility settings window with 'Reduce motion' setting enabled"
    height="400"
    src="https://i.imgur.com/lKzETqa.png"
  />
</p>

Combine `skipAnimation` with [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) to gracefully disable or reduce the motion of your animations. [react-reduce-motion](https://github.com/infiniteluke/react-reduce-motion) is a cross platform hook that exposes this OS level setting, enabling you to disable or lessen your animations for users that want to opt out.

To disable animations using this hook you can use react-spring's `skipAnimation` global:

```jsx
import { useReducedMotion } from 'react-reduce-motion'
import { Globals } from 'react-spring'

const MyApp = () => {
  const prefersReducedMotion = useReducedMotion()
  React.useEffect(() => {
    Globals.assign({
      skipAnimation: prefersReducedMotion,
    })
  }, [prefersReducedMotion])
  // ...
}
```

Animations can also be disable on a case by case basis using the `immediate` property.

```jsx
import { useReducedMotion } from 'react-reduce-motion'

const MyComponent = () => {
  const prefersReducedMotion = useReducedMotion()
  const props = useSpring({ opacity: 1, immediate: prefersReducedMotion })
  // ...
}
```

Finally, animations can be lessened by applying your own heuristic.

```jsx
import { useReducedMotion } from 'react-reduce-motion'

const MyComponent = () => {
  const prefersReducedMotion = useReducedMotion()
  const props = useSpring({
    scale: prefersReducedMotion ? '1.05' : '2',
  })
  // ...
}
```

Check out [react-reduce-motion](https://github.com/infiniteluke/react-reduce-motion) to learn more.


Accessibility


If you want to see a setup guide and example with the testing framework you use that isn't documented here, why not consider submitting a [PR](https://github.com/pmndrs/react-spring)?

## Setup with Jest

## The Problem

If you test a component that has react-spring's render-props in it, you might come across this error:

```bash
path\to\project\node_modules\react-spring\renderprops.js:1
    ({"Object.<anonymous>":function(module,exports,require,__dirname,__filename,global,jest){import _objectWithoutPropertiesLoose from '@babel/runtime/helpers/esm/objectWithoutPropertiesLoose';
```

And interestingly, your component works fine on a browser, and no errors are to be found in the console!

This is because Jest is using the ESM file instead of the CJS one, which is what Node understands. Normally, Jest will look for the main field in `package.json`, which might explain why it works in the previous version of react-spring.

### The Solution

To make sure Jest picks up the CJS file instead of the ESM file, add this the the Jest configuration file (`jest.config.js`):

```js
module.exports = {
  moduleNameMapper: {
    'react-spring': '<rootDir>/node_modules/react-spring/web.cjs',
  },
}
```

Or if you prefer to do it in `package.json`:

```js
"jest": {
  "moduleNameMapper": {
    "react-spring": "<rootDir>/node_modules/react-spring/web.cjs",
  }
}
```

#### React Native

If you are using React Native and are importing from `@react-spring/native`, then you'll also need to map this module to the CJS file.

```js
module.exports = {
  moduleNameMapper: {
    '@react-spring/native': '<rootDir>/node_modules/react-spring/native.cjs',
  },
}
```

### Ok, let's try it out!

In `Thing.test.js` copy the following (Notice we are using Enzyme for this example)

```js
import React from 'react'
import { shallow } from 'enzyme'
import { Spring, animated } from 'react-spring'

const Thing = () => (
  <Spring native from={{ opacity: 0 }} to={{ opacity: 1 }}>
    {(style) => <animated.div style={style}>It works!</animated.div>}
  </Spring>
)

describe('react-spring component test', () => {
  it('works!', () => {
    expect(shallow(<Thing />).exists()).toBe(true)
  })
})
```

And Hooray!

![nh](https://user-images.githubusercontent.com/43169879/53028522-f005e880-345e-11e9-9b91-c9d6610c146e.png)



## v9.1.2

### Fixes

- revert changes from [#1023](https://github.com/pmndrs/react-spring/pull/1023) because of a misunderstanding of the API
- resolve [#1419](https://github.com/pmndrs/react-spring/issues/1419) where `onStart` and `onRest` were not fired causing a build up of events in the queue.

### Chores

- Updating demos to work with `react-spring.io`

## v9.1.0

### Features

- We listened to the feedback people had, so whilst we encourage people to use the pattern `[styles, api] = useSpring()` we have aliased calling `api` to be `api.start` [#1359](https://github.com/pmndrs/react-spring/issues/1359)
- `POTENTIALLY BREAKING CHANGE` We've unified the return of all events `onStart`, `onChange`, `onRest` etc. to be the following - `(animationResult, controller, item)` item will only not be `undefined` when using `useTransition`.

### Fixes

- scrollTop is not set when from & to are equal [#1185](https://github.com/pmndrs/react-spring/issues/1185)
- skip animation with async to infinite loop [#1160](https://github.com/pmndrs/react-spring/issues/1160)
- Stop jank in animation when duration changes on SpringValue [#1163](https://github.com/pmndrs/react-spring/issues/1163)

### Chores

- We have our test suite working again! hooray, it means we can review and commit PR's quicker and more effectively
- We've updated all our examples in this repo to v9 [#1386](https://github.com/pmndrs/react-spring/pull/1386)

## v9.0.0

Say hello 👋 to **react-spring v9.0.0**, which comes with useful new features and fixes!!

You might run into _breaking changes_ 👻, so be sure your animations still work after upgrading.

### Unified API

In the past two major versions, the "Render Props API" and "Hooks API" were provided by separate modules. In fact, each API had its own implementation of the internal `Controller` class, which was bad for maintenance.

```jsx
import { useSpring } from 'react-spring'
import { Spring } from 'react-spring/renderprops'
```

The new version unifies these APIs into a single module!

```jsx
import { Spring, useSpring } from 'react-spring'

// The legacy module is still available:
import { Spring } from 'react-spring/renderprops'
```

⚠️ Note: Using `auto` as an end value is not supported by the `react-spring` module, but the `react-spring/renderprops` module still supports it.

### Improved types

TypeScript definitions have been rewritten for a better experience.

<br />

Changes include the following:

- Added tests to ensure types are never broken
- Smarter type inference
- More inline documentation

### Time-based diffing

"Time-based diffing" is a new strategy used when updating the props. It uses timestamps to know when props have been overridden.
In practice, this means that delayed animations can be selectively overridden without needing to call `stop` first.

```jsx
useSpring({
  from: { width: 10, height: 10 },
  to: async (next) => {
    // Create a delayed animation
    next({ width: 100, height: 100, delay: 2000 }) // 2 seconds
    // Immediately override the width animation
    next({ width: 50 }) // This creates a new animation which starts immediately,
    // and it prevents the delayed animation from changing
    // the width. The height will still animate in 2 seconds.
  },
})
```

This behavior comes in handy with `useTransition` when an `enter` animation only partially conflicts with an `update` or `leave` animation.

```jsx
useTransition(items, null, {
  from: { size: 0, color: 'green' },
  enter: { size: 100, color: 'black' },
  leave: { size: 0 }, // Once the "leave" animation begins, the "color" will continue
}) // animating from "green" to "black" since it never changed.
```

### Improved `useTransition`

You might know that the `enter`, `update`, and `leave` props of `useTransition` accept function values so you can customize the animations on an item-by-item basis.

```jsx
useTransition(items, {
  from: { width: 0 },
  enter: (item) => ({ width: item.width }),
})
```

In the past, the object returned by `enter` wasn't able to configure the animation, except for its `to` values. Now, you're free to include any props that can be passed to `useSpring`!

```jsx
useTransition(items, {
  from: { width: 0 },
  enter: (item) => ({
    width: item.width,
    delay: item.delay, // Per-item delay
    config: { duration: item.duration }, // Per-item spring config
    onChange: (frame) => {
      // Per-item event listeners
      console.log('onChange:', frame)
    },
  }),
})
```

### Improved async animations

Async animations are created when an array or async function is passed to `useSpring` as the `to` prop. Pass an array to create a chain of animations. Pass an async function to create animations on-the-fly by repeatedly calling the given `next` function.

```jsx
// Chaining with an array
useSpring({
  to: [{ opacity: 1 }, { color: 'red' }],
  from: { opacity: 0, color: 'black' },
})

// Chaining with an async function
useSpring({
  to: async (next) => {
    await next({ opacity: 1 })
    await next({ color: 'red' })
  },
  from: { opacity: 0, color: 'black' },
})
```

In the new version, the objects of your arrays and `next` calls are allowed to include any props that can be passed to `useSpring`.

```jsx
// Chaining with an array
useSpring({
  to: [
    { opacity: 1, config: { duration: 1000 } },
    { color: 'red', delay: 1000 },
  ],
  from: { opacity: 0, color: 'black' },
})

// Chaining with an async function
useSpring({
  to: async (next) => {
    await next({ opacity: 1, config: { duration: 1000 } })
    await next({ color: 'red', delay: 1000 })
  },
  from: { opacity: 0, color: 'black' },
})
```

⚠️ Additionally, async animations are no longer cancelled when the props are updated. Async chains (eg: `{`to: [{}, {}]`}`) are never cancelled, even if another chain begins. Async scripts (eg: `{`to: async () => {}`}`) are only interrupted when another script or chain begins.

### Added `cancel` prop

The `cancel` prop can be used anywhere the `reset` prop can be (eg: `useSpring`).

- When true, all animations are cancelled.
- When false, all animations are resumed.
- When a string, a single key has its animation cancelled.
- When an array of strings, multiple keys may have their animations cancelled.

```jsx
const props = useSpring({
cancel: true, // Cancel all animations
opacity: 1,
})

const props = useSpring({
cancel: 'foo', // Cancel the "foo" animation only
from: { foo: 0, bar: 0 }
to: { foo: 1, bar: 1 },
})

const props = useSpring({
cancel: ['foo', 'bar'], // Cancel multiple animations by key
from: { foo: 0, bar: 0 }
to: { foo: 1, bar: 1 },
})
```

The `reset` prop is ignored for all keys cancelled by the `cancel` prop.

### Improved `stop` function

When you pass a function as the first argument, the `useSpring` function returns two functions (one for updates, one for stops).

```js
const [props, update, stop] = useSpring(() => ({ opacity: 1 }))
```

Previously, the `stop` function wouldn't actually stop any animations, which made it seem broken.

In this version, it will stop _all_ animations (and prevent any delayed animations!) when called with no arguments. Additionally, you can pass an animated key (eg: `"opacity"`) if you only want to stop one property from animating.

```jsx
stop() // Stop all animations
stop('opacity') // Stop only the "opacity" animation
stop('opacity', 'width') // Stop "opacity" and "width"

stop(true) // Stop all animations and pretend like they finished
stop(true, 'width') // Stop "width" and pretend like it finished
```

### Repurposed `onStart` prop

The `onStart` prop is now called whenever an animated key is about to start animating to a new value. Previously, it was called every time the props were updated (even when no animations were actually started), which proved to be unreliable.

```jsx
useSpring({
  opacity: 1,
  from: { opacity: 0 },
  onStart(animation) {
    console.log(`Animating "${animation.key}":`, animation)
  },
})
```

### Reworked dependency injection

Dependency injection lets react-spring be compatible with multiple platforms. To support a new platform, you can import the `react-spring/universal` module and interact with its `Globals` export. To get an idea of how this is done, you can check out the existing platforms (eg: `src/targets/web.js`).

In v9.0.0, the `Globals` export now comes with only an `assign` method, instead of calling functions with names like `Globals.injectRequestFrame()`. The `Globals.assign` method takes an object of injected dependencies. You are not required to inject all possible dependencies, since most have sane defaults.

```jsx
import { Globals } from 'react-spring/universal'

// The old way
Globals.injectDefaultElement(View)
Globals.injectStringInterpolator(createStringInterpolator)
Globals.injectColorNames(colorNames)
Globals.injectApplyAnimatedValues(
  (instance, props) => (instance.setNativeProps ? instance.setNativeProps(props) : false),
  (style) => ({ ...style, transform: new AnimatedTransform(style.transform) })
)

// The new way
Globals.assign({
  defaultElement: View,
  createStringInterpolator,
  applyAnimatedValues: (instance, props) =>
    instance.setNativeProps ? instance.setNativeProps(props) : false,
  createAnimatedTransform: (transform) => new AnimatedTransform(transform),
})
```

Note: When using the `react-spring/universal` module, you must inject the `applyAnimatedValues` function. Everything else is optional. For other modules like `react-spring/native`, the required globals are injected for you.

```ts
export interface AnimatedGlobals {
  // Defaults to \`Date.now\`
  now?: () => number
  // To support colors like "red". Defaults to \`{}\`
  colorNames?: { [key: string]: number }
  // Usually the "div" of the platform. Defaults to \`undefined\`
  defaultElement?: any
  // Update the values of the affected nodes. Required
  applyAnimatedValues?: (node: any, props: object) => boolean | void
  // Wrap the \`transform\` property of an animated style
  createAnimatedTransform?: (transform: any) => any
  // Wrap the \`style\` property of an animated component
  createAnimatedStyle?: (style: any) => any
  // Create the \`ref\` API of an animated component
  createAnimatedRef?: (
    node: { current: any },
    mounted?: { current: boolean },
    forceUpdate?: () => void
  ) => { current: any }
  // Defaults to \`window.requestAnimationFrame\`
  requestAnimationFrame?: (onFrame: () => void) => number
  // Defaults to \`window.cancelAnimationFrame\`
  cancelAnimationFrame?: (handle: number) => void
  // Called on every frame. Defaults to \`undefined\`
  manualFrameloop?: () => void
  // Custom string interpolation. Defaults to \`undefined\`
  interpolation?: (config: object) => (input: number) => number | string
}
```

### Reworked `Controller` API

Lastly, for anyone interested in an imperative API, here's an example that demonstrates time-based diffing using the `Controller` class, which had a massive rewrite in v9.0.0.

```jsx
import { Controller, animated } from 'react-spring'

// Create a controller (aka: the manual API)
const spring = new Controller({
opacity: 1, // The initial props
width: '100%',
height: '100%',
backgroundColor: 'red',
})

// Inspect when each prop was last updated
console.log(spring.timestamps) // => { "to.opacity": now,
                                //      "to.width": now,
                                //      "to.height": now,
                                //      "to.backgroundColor": now }

// Use the animated values
<animated.div style={spring} />

// Create a delayed animation
spring.update({
opacity: 0,
width: '50%',
delay: 2000,
}).start(values => {
console.log('Final values:', values)
})

// Notice the props have not changed yet
assert(spring.props.opacity === 1)
assert(spring.props.width === '100%')

// You can override any prop (except the "delay" prop)
spring.update({
opacity: 0.5, // This prevents the delayed animation from changing the opacity.
}).start()      // NOTE: The width will still animate to "50%" two seconds from now.

// Other methods
spring.stop('opacity', 'width')
spring.destroy()
```

## react-spring 8.0

### Breaking changes

Migrating from 7.x to 8.0 is painless. The only breaking change is the default export. If you have previously done something like this:
`jsx import { Spring, animated, ... } from 'react-spring'`
Then you will now do:
`jsx import { Spring, animated, ... } from 'react-spring/renderprops'`
And if you have previously used hooks like so:
`jsx import { useSpring, animated, ... } from 'react-spring/hooks'`
You will now do:
`jsx import { useSpring, animated, ... } from 'react-spring'`
The lib comes with the following exports:

```bash
web (web/hooks, default for react-dom)
native (react-native/hooks, default for react-native)
renderprops-web (previously "web")
renderprops-native (previously "native")
renderprops-addons (previously "addons")
renderprops-konva (previously "konva")
renderprops-universal (previously "universal")
```

For commonjs, add ".cjs"
Both render-props and hooks will be kept and maintained for the foreseeable future.

#### useTransition

```jsx
useTransition(items, keys, config)
```

See: <a href="/react-spring/hooks/use-transition">useTransition</a>

## react-spring 7.0

- ☂️ Hooks! useSpring, useTransition, useTrail & useKeyframes available under `react-spring/hooks`
- ✨ addons, native, konva and universal are available directly without `/dist/`
- 🐞 Bugfixes ...

### Breaking changes

Nothing, except the removal of `/dist/`, and the experimental useSpring export moved to `/hooks`. Should be good to go! 😊

## react-spring 6.0

- ⚡️ React strict-mode compliant and ready for async rendering
- 🚀 New spring engine (from RK4 to SEE), lots of internal changes making it faster and leaner
- ✨ Simpler and more intuitive api

### Configs

- ⏰ Duration is built in and as easy as going `{`config={{ duration: 1000, easing: ... }}`}`
- ⌛️ Delays can be driven per config `{`config={{ delay: 1000, ... }}`}`
- ✨ Simpler property names (mass, tension, friction, delay, precision, clamp, velocity, duration, easing)
- 🎩 Spring config props are 1:1 compatible with react-motions and the presets finally do what they say

### Springs

- ⏮ Springs can run `reverse`, which switches `from` and `to`
- 🚬 The `after` prop makes it easier to apply static values at the end of an animation
- 🐉 Springs can animate scrollTop/Left

### Transitions

- 🎉 Multistage transitions are finally possible. `Transition` inherits from `Keyframes` now, which allows it to receive the same values that you can use in slots, meaning you can chain or even script transitions
- ⭐️ The `unique` prop prevents two children with the same key to co-exist, which was an often asked for suggestion. If it is true, a fading-out item will vanish when an item with the same key comes in again, as opposed to forming a stack (which is still the default)
- ✖️ The `reset` prop, in combination with `unique` forces an incoming item to always start from scratch instead of adapting the fading-out item to take start-position
- 🐌 Transitions can trail using the `trail` prop which takes a duration in ms
- ✨ Simpler api. Previously you could optionally pass `items` and you would have to map over children yourself. `items` and `keys` are Transitions sole source of truth now. You give a single function child instead of mapping
- 🎮 Transition behaves more like Reacts TransitionGroup in that it can give you way more contextual information than before, you even have access to the state your output component is in (enter/leave/update)

### Trails

- ✨ Simpler api. Same as Transitions
- ⏮ The `reverse` prop can move a trail bottom-up instead of the default top-down which is more natural for items swinging in and out

### Keyframes

- ✨ Simpler api. You don't have to write `{`to: {...}`}` any longer since everything is interpolated to it

### Parallax

- 🤷‍ Parallax always felt off since it's not as generic as the others. It has been moved to `react-spring/dist/addons` and could mark the start of convenience components or effects that don't belong anywhere else

### Upgrading to 6.0

The changes made are mostly features, the api changes are slight and looking at the front page here will tell you immediately what to do. You will probably have to adapt your Transitions and Trail, Keyframes are backwards compatible. If you have used timings off `dist/addons` before, duration is now inbuilt (see above). A noticeable change also concerns spring config props, where before we would be closer to how the animated library interprets tension and friction we are now 1:1 compatible with react-motion.


Changelog


![logo](/logo-drei.jpg)

A growing collection of useful helpers and abstractions for [react-three-fiber](https://github.com/pmndrs/react-three-fiber).

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

👉 this package is using the stand-alone [`three-stdlib`](https://github.com/pmndrs/three-stdlib) instead of [`three/examples/jsm`](https://github.com/mrdoob/three.js/tree/dev/examples/jsm). 👈

### Basic usage:

```jsx
import { PerspectiveCamera, PositionalAudio, ... } from '@react-three/drei'
```

### React-native:

```jsx
import { PerspectiveCamera, PositionalAudio, ... } from '@react-three/drei/native'
```

The `native` route of the library **does not** export `Html` or `Loader`. The default export of the library is `web` which **does** export `Html` and `Loader`.



A component for applying a configurable camera shake effect. Currently only supports rotational camera shake. Pass a ref to receive the `ShakeController` API.

```jsx
const config = {
  maxYaw: 0.1, // Max amount camera can yaw in either direction
  maxPitch: 0.1, // Max amount camera can pitch in either direction
  maxRoll: 0.1, // Max amount camera can roll in either direction
  yawFrequency: 1, // Frequency of the the yaw rotation
  pitchFrequency: 1, // Frequency of the pitch rotation
  rollFrequency: 1, // Frequency of the roll rotation
  intensity: 1, // initial intensity of the shake
  decay: false, // should the intensity decay over time
  decayRate: 0.65, // if decay = true this is the rate at which intensity will reduce at
  additive: false, // this should be used when your scene has orbit controls
}

<CameraShake {...config} />


interface ShakeController {
  getIntensity: () => number
  setIntensity: (val: number) => void
}
```

<StoryBook lib="drei" id="camera-camerashake--camera-shake-st" />


CameraShake


If available, controls have damping enabled by default. They manage their own updates, remove themselves on unmount, are compatible with the `invalidateFrameloop` canvas-flag. They inherit all props from their underlying [three.js controls](https://github.com/mrdoob/three.js/tree/dev/examples/jsm/controls).

Every control component can be used with a custom camera using the `camera` prop:

```jsx
const [camera, set] = useState()

return (
  <>
    <PerspectiveCamera ref={set} position={[0, 5, 5]} />
    <OrbitControls camera={camera} />
  </>
)
```

PointerLockControls additionally supports a `selector` prop, which enables the binding of `click` event handlers for control activation to other elements than `document` (e.g. a 'Click here to play' button).



Adds a `<Plane />` that always faces the camera.

```jsx
<Billboard
  follow={true} // Follow the camera (default=true)
  lockX={false} // Lock the rotation on the x axis (default=false)
  lockY={false} // Lock the rotation on the y axis (default=false)
  lockZ={false} // Lock the rotation on the z axis (default=false)
/>
```


Billboard


A [contact shadow](https://threejs.org/examples/?q=con#webgl_shadow_contact) implementation.

```jsx
<ContactShadows
  opacity={1}
  width={1}
  height={1}
  blur={1} // Amount of blur (default=1)
  far={10} // Focal distance (default=10)
  resolution={256} // Rendertarget resolution (default=256)
/>
```

<StoryBook lib="drei" id="shaders-contactshadows--contact-shadow-st" />


ContactShadows


Calculates a boundary box and centers its children accordingly. `alignTop` makes adjusts it so that it's sits flush on y=0.

```jsx
<Center alignTop>
  <mesh />
</Center>
```

<StoryBook lib="drei" id="misc-center--default-story" />


Center


A quick and easy loading overlay component that you can drop on top of your canvas. It's intended to "hide" the whole app, so if you have multiple suspense wrappers in your application, you should use multiple loaders. It will show an animated loading bar and a percentage.

```jsx
<Canvas>
  <Suspense fallback={null}>
    <AsyncModels />
  </Suspense>
</Canvas>
<Loader />
```

You can override styles, too.

```jsx
<Loader
  containerStyles={...container} // Flex layout styles
  innerStyles={...inner} // Inner container styles
  barStyles={...bar} // Loading-bar styles
  dataStyles={...data} // Text styles
  dataInterpolation={(p) => `Loading ${p.toFixed(2)}%`} // Text
  initialState={(active) => active} // Initial black out state
>
```

<Hint>Only works in the DOM</Hint>


Loader


Given a curve will replace the children of this component with a mesh that move along said curve calling the property `moveAlongCurve` on the passed ref. Uses [three's Curve Modifier](https://threejs.org/examples/?q=curve#webgl_modifier_curve)

```jsx
const curveRef = useRef()

const curve = React.useMemo(() => new THREE.CatmullRomCurve3([...handlePos], true, 'centripetal'), [
  handlePos,
])

return (
  <CurveModifier ref={curveRef} curve={curve}>
    <mesh>
      <boxBufferGeometry args={[10, 10]} />
    </mesh>
  </CurveModifier>
)
```

<StoryBook lib="drei" id="modifiers-curvemodifier" />


CurveModifier

Creates a "stage" with proper studio lighting, content centered and planar, shadows and ground-contact shadows.

```jsx
<Stage
  contactShadow // Optional: creates a contactshadow underneath the content (default=true)
  shadows // Optional: lights cast shadow (default=true)
  adjustCamera // Optional: zooms the content in (default=true)
  intensity={1} // Optional: light intensity (default=1)
  environment="city" // Optional: environment (default=city)
  preset="rembrandt" // Optional: rembrandt (default) | portrait | upfront | soft
  controls={controlsRef} // Optional: recalculates control target for correctness
>
  <mesh />
</Stage>
```

Stage


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for box.

```jsx
<Box>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Box>
```

<StoryBook lib="drei" id="shapes--box" />



Drop this component into your scene and it will cut the pixel-ratio on [regress](#) according to the canvases performance min/max settings. This allows you to temporarily reduce visuals for more performance, for instance when the camera moves (look into drei's controls `regress` flag). Optionally you can set the canvas to a pixelated filter, which would be even faster.

```jsx
<AdaptiveDpr pixelated />
```


AdaptiveDpr


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for Tube that creates a tube that extrudes along a 3d curve.

```jsx
<Tube args={[path]}>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Tube>
```

<StoryBook lib="drei" id="shapes-tube--tube-st" />


Tube


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for torus.

```jsx
<Torus>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Torus>
```

<StoryBook lib="drei" id="shapes--torus" />


Torus


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for TorusKnot.

```jsx
<TorusKnot>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</TorusKnot>
```

<StoryBook lib="drei" id="shapes--torus-knot" />


TorusKnot


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for tetrahedron.

```jsx
<Tetrahedron>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Tetrahedron>
```

<StoryBook lib="drei" id="shapes--tetrahedron" />


Tetrahedron


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for sphere.

```jsx
<Sphere>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Sphere>
```

<StoryBook lib="drei" id="shapes--sphere" />


Sphere


```jsx
<ScreenQuad>
  <myMaterial />
</ScreenQuad>
```

A triangle that fills the screen, ideal for full-screen fragment shader work (raymarching, postprocessing).

👉 [Why a triangle?](https://www.cginternals.com/en/blog/2018-01-10-screen-aligned-quads-and-triangles.html)

👉 [Use as a post processing mesh](https://medium.com/@luruke/simple-postprocessing-in-three-js-91936ecadfb7)

<StoryBook lib="drei" id="shapes-screenquad--screen-quad-st" />


ScreenQuad


A box buffer geometry with rounded corners, done with extrusion.

```jsx
<RoundedBox
  args={[1, 1, 1]} // Width, Height and Depth of the box
  radius={0.05} // Border-Radius of the box
  smoothness={4} // Optional, number of subdivisions
  {...meshProps} // All THREE.Mesh props are valid
>
  <meshPhongMaterial attach="material" color="#f3f3f3" wireframe />
</RoundedBox>
```

<StoryBook lib="drei" id="shapes-roundedbox--rounded-box-st" />


RoundedBox


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for ring.

```jsx
<Ring>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Ring>
```

<StoryBook lib="drei" id="shapes--ring" />


Ring


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for polyhedron.

```jsx
// prettier-ignore
const verticesOfCube = [
  -1, -1, -1, 1, -1, -1, 1, 1, -1, -1, 1, -1,
  -1, -1, 1, 1, -1, 1, 1, 1, 1, -1, 1, 1,
];

// prettier-ignore
const indicesOfFaces = [
  2, 1, 0, 0, 3, 2,
  0, 4, 7, 7, 3, 0,
  0, 1, 5, 5, 4, 0,
  1, 2, 6, 6, 5, 1,
  2, 3, 7, 7, 6, 2,
  4, 5, 6, 6, 7, 4
];
return (
  <Polyhedron args={[verticesOfCube, indicesOfFaces]}>
    <meshPhongMaterial attach="material" color="#f3f3f3" />
  </Polyhedron>
)
```

<StoryBook lib="drei" id="shapes--polyhedron" />


Polyhedron


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for plane.

```jsx
<Plane>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Plane>
```

<StoryBook lib="drei" id="shapes--plane" />


Plane


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for Parametric that generates geometry representing a parametric surface.

```jsx
<Parametric args={[ParametricGeometries.klein, 25, 25]}>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Parametric>
```

<StoryBook lib="drei" id="shapes-parametric--parametric-st" />


Parametric


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for octahedron.

```jsx
<Octahedron>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Octahedron>
```

<StoryBook lib="drei" id="shapes--octahedron" />


Octahedron


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for Lathe that creates meshes with axial symmetry like vases. The lathe rotates around the Y axis.

```jsx
<Lathe args={[points]}>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Lathe>
```

<StoryBook lib="drei" id="shapes-lathe--lathe-st" />


Lathe


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for icosahedron.

```jsx
<Icosahedron>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Icosahedron>
```

<StoryBook lib="drei" id="shapes--icosahedron" />


Icosahedron


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for Extrude that creates extruded geometry from a path shape.

```jsx
const extrudeSettings = React.useMemo(
  () => ({
    steps: 2,
    depth: 16,
    bevelEnabled: true,
    bevelThickness: 1,
    bevelSize: 1,
    bevelOffset: 0,
    bevelSegments: 1,
  }),
  []
)

return (
  <>
    <Extrude args={[shape, extrudeSettings]}>
      <meshPhongMaterial attach="material" color="#f3f3f3" wireframe />
    </Extrude>
  </>
)
```

<StoryBook lib="drei" id="shapes-extrude--extrude-st" />


Extrude


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for dodecahedron.

```jsx
<Dodecahedron>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Dodecahedron>
```

<StoryBook lib="drei" id="shapes--dodecahedron" />


Dodecahedron


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for cylinder.

```jsx
<Cylinder>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Cylinder>
```

<StoryBook lib="drei" id="shapes--cylinder" />


Cylinder


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for cone.

```jsx
<Cone>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Cone>
```

<StoryBook lib="drei" id="shapes--cone" />


Cone


[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cut for circle.

```jsx
<Circle>
  <meshPhongMaterial attach="material" color="#f3f3f3" />
</Circle>
```

<StoryBook lib="drei" id="shapes--circle" />


Circle


Adds a blinking shader-based starfield to your scene.

```jsx
<Stars
  radius={100} // Radius of the inner sphere (default=100)
  depth={50} // Depth of area where stars should fit (default=50)
  count={5000} // Amount of stars (default=5000)
  factor={4} // Size factor (default=4)
  saturation={0} // Saturation 0-1 (default=0)
  fade // Faded dots (default=false)
/>
```

<StoryBook lib="drei" id="shaders-stars--stars-st" />


Stars


Injects [percent closer soft shadows (pcss)](https://threejs.org/examples/?q=pcss#webgl_shadowmap_pcss) into threes shader chunk.

```jsx
softShadows({
  frustum: 3.75, // Frustum width (default: 3.75) must be a float
  size: 0.005, // World size (default: 0.005) must be a float
  near: 9.5, // Near plane (default: 9.5) must be a float
  samples: 17, // Samples (default: 17) must be a int
  rings: 11, // Rings (default: 11) must be a int
})
```

<StoryBook lib="drei" id="shaders-softshadows--soft-shadows-st" />


softShadows


Adds a [sky](https://threejs.org/examples/webgl_shaders_sky.html) to your scene.

```jsx
<Sky
  distance={450000} // Camera distance (default=450000)
  sunPosition={[0, 1, 0]} // Sun position normal (defaults to inclination and azimuth if not set)
  inclination={0} // Sun elevation angle from 0 to 1 (default=0)
  azimuth={0.25} // Sun rotation around the Y axis from 0 to 1 (default=0.25)
  {...props} // All three-stdlib/objects/Sky props are valid
/>
```

<StoryBook lib="drei" id="shaders-sky--sky-st" />



Creates a [`THREE.ShaderMaterial`](https://threejs.org/docs/?q=ShaderMaterial#api/en/materials/ShaderMaterial) for you with easier handling of uniforms, which are also automatically declared as setter/getters on the object.

```jsx
import { extend } from '@react-three/fiber'
import glsl from 'babel-plugin-glsl/macro'

const ColorShiftMaterial = shaderMaterial(
  { time: 0, color: new THREE.Color(0.2, 0.0, 0.1) },
  // vertex shader
  glsl`
    varying vec2 vUv;
    void main() {
      vUv = uv;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  // fragment shader
  glsl`
    uniform float time;
    uniform vec3 color;
    varying vec2 vUv;
    void main() {
      gl_FragColor.rgba = vec4(0.5 + 0.3 * sin(vUv.yxx + time) + color, 1.0);
    }
  `
)

extend({ ColorShiftMaterial })

// in your component
<mesh>
  <colorShiftMaterial attach="material" color="hotpink" time={1} />
</mesh>
```

<StoryBook lib="drei" id="shaders-shadermaterial--shader-material-story" />


shaderMaterial


This material makes your geometry wobble and wave around. It was taken from the [threejs-examples](https://threejs.org/examples/#webgl_materials_modified) and adapted into a self-contained material.

```jsx
<mesh>
  <boxBufferGeometry attach="geometry" />
  <MeshWobbleMaterial
    attach="material"
    factor={1} // Strength, 0 disables the effect (default=1)
    speed={10} // Speed (default=1)
  />
</mesh>
```

<StoryBook lib="drei" id="shaders-meshwobblematerial--mesh-wobble-material-st" />


MeshWobbleMaterial


This material makes your geometry distort following noise.

```jsx
<mesh>
  <boxBufferGeometry attach="geometry" />
  <MeshDistortMaterial
    attach="material"
    distort={1} // Strength, 0 disables the effect (default=1)
    speed={10} // Speed (default=1)
  />
</mesh>
```

<StoryBook lib="drei" id="shaders-meshdistortmaterial--mesh-distort-material-st" />


MeshDistortMaterial


Loads normal textures from this repository: [https://github.com/emmelleppi/normal-maps](https://github.com/emmelleppi/normal-maps)

```jsx
const [normalMap, url] = useNormalTexture(
  1, // index of the normal texture - https://github.com/emmelleppi/normal-maps/blob/master/normals.json
  // second argument is texture attributes
  {
    offset: [0, 0],
    repeat: [normRepeat, normRepeat],
    anisotropy: 8
  }
)

return (
  ...
  <meshStandardMaterial normalMap={normalMap} />
  ...
)

```

<StoryBook lib="drei" id="prototyping-usenormaltexture" />


useNormalTexture


Loads matcap textures from this repository: [https://github.com/emmelleppi/matcaps](https://github.com/emmelleppi/matcaps)

(It is a fork of this repository:[ https://github.com/nidorx/matcaps](https://github.com/emmelleppi/matcaps))

```jsx
const [matcap, url] = useMatcapTexture(
 0, // index of the matcap texture https://github.com/emmelleppi/matcaps/blob/master/matcap-list.json
 1024 // size of the texture ( 64, 128, 256, 512, 1024 )
)

return (
 ...
 <meshMatcapMaterial matcap={matcap} />
 ...
)
```

👉 You can also use the exact name of the matcap texture, like so:

```jsx
const [matcap] = useMatcapTexture('3E2335_D36A1B_8E4A2E_2842A5')
```

<StoryBook lib="drei" id="prototyping-usematcaptexture" />


useMatcapTexture


The WebGLRenderer will compile materials only when they hit the frustrum, which can cause jank. This component precompiles the scene using [gl.compile](https://threejs.org/docs/index.html#api/en/renderers/WebGLRenderer.compile) which makes sure that your app is responsive from the get go.

By default gl.compile will only preload visible objects, if you supply the `all` prop, it will circumvent that. With the `scene` and `camera` props you could also use it in portals.

If you have async models you can drop it into the same suspense boundary _in concurrent mode_.

```jsx
<Canvas concurrent>
  <Suspense fallback={null}>
    <Model />
    <Preload all />
```


Preload


A very fast, but often good-enough bounds-only raycast for meshes. You can use this if performance has precedence over pointer precision.

```jsx
<mesh raycast={meshBounds} />
```

<StoryBook lib="drei" id="misc-meshbounds--mesh-bounds-st" />


meshBounds


A wrapper around [`THREE.LOD`](https://threejs.org/docs/index.html#api/en/objects/LOD) (Level of detail).

```jsx
<Detailed
  distances={[0, 10, 20]} // Camera distances, correspends to the # of the children
  {...props} // All THREE.LOD props are valid
>
  <mesh geometry={highDetail} />
  <mesh geometry={mediumDetail} />
  <mesh geometry={lowDetail} />
</Detailed>
```

<StoryBook lib="drei" id="abstractions-detailed--detailed-st" />


Detailed


Drop this component into your scene and it will switch off the raycaster while the system is in regress.

```jsx
<AdaptiveEvents />
```


AdaptiveEvents


This hook mutates a mesh geometry using [three's Tessellation modifier](https://threejs.org/examples/?q=tess#webgl_modifier_tessellation). It will break-up faces with edge longer than the maxEdgeLength parameter.

```jsx
const meshRef = useTessellation(
  2, // passes - number of times the geometry will be subdivided
  8 // maxEdgeLength - faces with edges longer than this number will be broken up
)

return (
  <mesh ref={meshRef}>
    <octahedronBufferGeometry args={[2, 2]} />
  </mesh>
)
```

<StoryBook lib="drei" id="modifiers-usetessellation" />


useTessellation


This hook mutates a mesh geometry using [three's Simplification modifier](https://threejs.org/examples/webgl_modifier_simplifier.html).

👉 The simplification code is based on [this algorithm](http://www.melax.com/polychop/).

```jsx
const meshRef = useSimplification(0.5) // the vertices will be halved

return (
  <mesh ref={meshRef}>
    <octahedronBufferGeometry args={[2, 5]} />
  </mesh>
)
```

<StoryBook lib="drei" id="modifiers-usesimplification" />


useSimplification


This hook mutates a mesh geometry using [three's Edge Split modifier](https://threejs.org/examples/?q=modifier#webgl_modifier_edgesplit). The first parameter is the cut-off angle, and the second parameter is a `tryKeepNormals` flag (default `true`).

```jsx
const meshRef = useEdgeSplit(Math.PI / 2)

return (
  <mesh ref={meshRef}>
    <boxBufferGeometry args={[10, 10]} />
  </mesh>
)
```

<StoryBook lib="drei" id="modifiers-useedgesplit" />


useEdgeSplit


A hook for a quick way to add helpers to existing nodes in the scene. It handles removal of the helper on unmount and auto-updates it by default.

```jsx
const mesh = useRef()
useHelper(mesh, BoxHelper, 'cyan')

<mesh ref={mesh} ... />
```

<StoryBook lib="drei" id="misc-usehelper--default-story" />


useHelper


Creates a `THREE.WebGLRenderTarget` or `THREE.WebGLMultisampleRenderTarget`.

```jsx
const target = useFBO(
  // width: 500,  height: 500,
  // width and height are optional and defaulted to the viewport size
  // multiplied by the renderer pixel ratio, and recalculated whenever the
  // viewport size changes.
  {
    multisample: true, // if the renderer supports webGL2, it will return a WebGLMultisampleRenderTarget
    stencilBuffer: false, // you can pass any options supported by THREE.WebGLRenderTarget
  }
)
```

The rendertarget is automatically disposed when unmounted.

<StoryBook lib="drei" id="misc-usefbo--use-fbo-st" />


useFBO


This hook uses [DetectGPU by @TimvanScherpenzeel](https://github.com/TimvanScherpenzeel/detect-gpu) to determine what tier should be assigned to the user's GPU.

👉 This hook CAN be used outside the react-three-fiber `Canvas`.

```jsx
const GPUTier = useDetectGPU()

// show a fallback for mobile or lowest tier GPUs
return (
  {(GPUTier.tier === "0" || GPUTier.isMobile) ? <Fallback /> : <Canvas>...</Canvas>
```

<StoryBook lib="drei" id="misc-usedetectgpu" />


useDetectGPU


Allows you to forward contexts provided above the `<Canvas />` to be consumed from within the `<Canvas />` normally

```jsx
function SceneWrapper() {
  // bridge any number of contexts
  const ContextBridge = useContextBridge(ThemeContext, GreetingContext)
  return (
    <Canvas>
      <ContextBridge>
        <Scene />
      </ContextBridge>
    </Canvas>
  )
}

function Scene() {
  // we can now consume a context within the Canvas
  const theme = React.useContext(ThemeContext)
  const greeting = React.useContext(GreetingContext)
  return (
    //...
  )
}
```

<StoryBook lib="drei" id="misc-usecontextbridge--use-context-bridge-st" />


useContextBridge


A hook for the rare case when you are using non-default cameras for heads-up-displays or portals, and you need events/raytracing to function properly (raycasting uses the default camera otherwise).

```jsx
<mesh raycast={useCamera(customCamera)} />
```

<StoryBook lib="drei" id="misc-usecamera--use-camera-st" />


useCamera


This hook calculates aspect ratios (for now only what in css would be `image-size: cover` is supported). You can use it to make an image fill the screen. It is responsive and adapts to viewport resize. Just give the hook the image bounds in pixels. It returns an array: `[width, height, 1]`.

```jsx
const scale = useAspect(
  1024,                     // Pixel-width
  512,                      // Pixel-height
  1                         // Optional scaling factor
)
return (
  <mesh scale={scale}>
    <planeBufferGeometry />
    <meshBasicMaterial map={imageTexture} />
```

<StoryBook lib="drei" id="misc-useaspect--default-story" />


useAspect


Adds [stats](https://github.com/mrdoob/stats.js/) to document.body. It takes over the render-loop!

```jsx
<Stats
  showPanel={0} // Start-up panel (default=0)
  className="stats" // Optional className to add to the stats container dom element
  {...props} // All stats.js props are valid
/>
```

You can choose to mount Stats to a different DOM Element - for example, for custom styling:

```jsx
const node = useRef(document.createElement('div'))

useEffect(() => {
  node.current.id = 'test'
  document.body.appendChild(node.current)

  return () => document.body.removeChild(node.current)
}, [])

return <Stats parent={parent} />
```

<StoryBook lib="drei" id="misc-stats--default-story" />


Stats


A cheap canvas-texture-based circular gradient.

```jsx
<Shadow
  color="black" // Color (default:black)
  colorStop={0} // First gradient-stop (default:0)
  opacity={0.5} // Alpha (default:0.5)
  fog={false} // Reacts to fog (default=false)
/>
```

<StoryBook lib="drei" id="misc-shadow--shadow-st" />


Shadow


Easily add reflections and/or blur to a planar surface. This reflector can also blur and takes surface roughness into account for a more realistic effect.

```jsx
<Reflector
  args={[1, 1]} // PlaneBufferGeometry arguments
  resolution={256} // Off-buffer resolution, lower=faster, higher=better quality
  mirror={0.5} // Mirror environment, 0 = texture colors, 1 = pick up env colors
  mixBlur={1.0} // How much blur mixes with surface roughness (default = 0), note that this can affect performance
  mixStrength={0.5} // Strength of the reflections
  depthScale={1} // Scale the depth factor (0 = no depth, default = 0)
  minDepthThreshold={0.9} // Lower edge for the depthTexture interpolation (default = 0)
  maxDepthThreshold={1} // Upper edge for the depthTexture interpolation (default = 0)
  depthToBlurRatioBias={0.25} // Adds a bias factor to the depthTexture before calculating the blur amount [blurFactor = blurTexture * (depthTexture + bias)]. It accepts values between 0 and 1, default is 0.25. An amount > 0 of bias makes sure that the blurTexture is not too sharp because of the multiplication with the depthTexture
  distortion={0} // Amount of distortion based on the distortionMap texture
  distortionMap={distortionTexture} // The red channel of this texture is used as the distortion map. Default is null
  debug={0} /* Depending on the assigned value, one of the following channels is shown:
    0 = no debug
    1 = depth channel
    2 = base channel
    3 = distortion channel
    4 = lod channel (based on the roughness)
  */
>
  {(Material, props) => <Material {...props}>}
</Reflector>
```

<StoryBook lib="drei" id="misc-reflector--reflector-st" />


Reflector


Allows you to tie HTML content to any object of your scene. It will be projected to the objects whereabouts automatically.

```jsx
<Html
  prepend // Project content behind the canvas (default: false)
  center // Adds a -50%/-50% css transform (default: false) [ignored in transform mode]
  fullscreen // Aligns to the upper-left corner, fills the screen (default:false) [ignored in transform mode]
  distanceFactor={10} // If set (default: undefined), children will be scaled by this factor, and also by distance to a PerspectiveCamera / zoom by a OrthographicCamera.
  zIndexRange={[100, 0]} // Z-order range (default=[16777271, 0])
  portal={domnodeRef} // Reference to target container (default=undefined)
  transform // If true, applies matrix3d transformations (default=false)
  sprite // Renders as sprite, but only in transform mode (default=false)
  calculatePosition={(el: Object3D, camera: Camera, size: { width: number; height: number }) => number[]} // Override default positioning function. May be removed in the future (default=undefined) [ignored in transform mode]
  {...groupProps} // All THREE.Group props are valid
  {...divProps} // All HTMLDivElement props are valid
>
  <h1>hello</h1>
  <p>world</p>
</Html>
```

The rendertarget is automatically disposed when unmounted.

<Hint>Only works in the DOM</Hint>

<StoryBook lib="drei" id="misc-html--html-st" />


Html


A convenience hook that uses `useLoader` and `TextureLoader`

```jsx
const texture = useTexture(url)
const [texture1, texture2] = useTexture([texture1, texture2])
```

<StoryBook lib="drei" id="loaders-texture" />


useTexture


A convenience hook that wraps `THREE.DefaultLoadingManager`'s progress status.

```jsx
function Loader() {
  const { active, progress, errors, item, loaded, total } = useProgress()
  return <Html center>{progress} % loaded</Html>
}

return (
  <Suspense fallback={<Loader />}>
    <AsyncModels />
  </Suspense>
)
```

If you don't want your progress component to re-render on all changes you can be specific as to what you need, for instance if the component is supposed to collect errors only. Look into [zustand](https://github.com/react-spring/zustand) for more info about selectors.

```jsx
const errors = useProgress((state) => state.errors)
```

👉 Note that your loading component does not have to be a suspense fallback. You can use it anywhere, even in your dom tree, for instance for overlays.

<StoryBook lib="drei" id="misc-useprogress--use-progress-scene-st" />


useProgress


A convenience hook that uses `useLoader` and `GLTFLoader`, it defaults to CDN loaded draco binaries (`https://www.gstatic.com/draco/v1/decoders/`) which are only loaded for compressed models.

```jsx
// Loads model, uses CDN draco when needed
useGLTF(url)

// Use local draco binaries from a custom path
useGLTF(url, '/draco-gltf')

// Preload asset (you would do this in global space, not inside a component!)
useGLTF.preload(url)
```

<StoryBook lib="drei" id="loaders-gltf" />


MapControls