
`react-postprocessing` is a [postprocessing](https://github.com/vanruesc/postprocessing) wrapper for [@react-three/fiber](https://github.com/pmndrs/react-three-fiber). This is not (yet) meant for complex orchestration of effects, but can save you [hundreds of LOC](https://twitter.com/0xca0a/status/1289501594698960897) for a straight forward effects-chain.

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

[![Bubbles](/react-postprocessing-images/bubbles.jpg)](https://m94xb.csb.app)

[![Control](/react-postprocessing-images/control.jpg)](https://5jgjz.csb.app)

<p align="middle">
  <i>These demos are real, you can click them! They contain the full code, too. 📦</i>
</p>

## Why postprocessing and not three/examples/jsm/postprocessing?

From [https://github.com/vanruesc/postprocessing](https://github.com/vanruesc/postprocessing#performance)

> This library provides an EffectPass which automatically organizes and merges any given combination of effects. This minimizes the amount of render operations and makes it possible to combine many effects without the performance penalties of traditional pass chaining. Additionally, every effect can choose its own blend function.
>
> All fullscreen render operations also use a single triangle that fills the screen. Compared to using a quad, this approach harmonizes with modern GPU rasterization patterns and eliminates unnecessary fragment calculations along the screen diagonal. This is especially beneficial for GPGPU passes and effects that use complex fragment shaders.

Postprocessing also supports srgb-encoding out of the box, as well as WebGL2 MSAA (multi sample anti aliasing), which is react-postprocessing's default, you get high performance crisp results w/o jagged edges.

## What does it look like?

Well, you can do pretty much anything, but here's an example combining a couple of effects ([live demo](https://codesandbox.io/s/vigorous-currying-3r6l2)).

<a href="https://codesandbox.io/s/vigorous-currying-3r6l2" target="_blank" rel="noopener">
  <img src="/react-postprocessing-images/control.jpg" alt="Bubbles Demo" />
</a>

```jsx
import React from 'react'
import { EffectComposer, DepthOfField, Bloom, Noise, Vignette } from '@react-three/postprocessing'
import { Canvas } from '@react-three/fiber'

function App() {
  return (
    <Canvas>
      {/* Your regular scene contents go here, like always ... */}
      <EffectComposer>
        <DepthOfField focusDistance={0} focalLength={0.02} bokehScale={2} height={480} />
        <Bloom luminanceThreshold={0} luminanceSmoothing={0.9} height={300} />
        <Noise opacity={0.02} />
        <Vignette eskil={false} offset={0.1} darkness={1.1} />
      </EffectComposer>
    </Canvas>
  )
}
```


What is React Postprocessing and how you can use it

Introduction


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


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



![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`.



<p align="center">
  <img width="500" src="/a11y/react-three-a11y-header.jpg" />
</p>

@react-three/a11y brings accessibility to webGL with easy-to-use react-three-fiber components:

- Focus and focus indication
- Tab index and keyboard navigation
- Screen reader support and alt-text
- Roles and cursor shapes
- Descriptive links

You can try a [live demo here](https://n4rzi.csb.app).
Open it with your favourite assistive tech to test it out !

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

## Quick overview to get started

### The A11yAnnouncer component

First, place the A11yAnnouncer component next to the R3F Canvas component. This component is critical since it manage some screen-reader features.

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

function App() {
  return (
    <>
      <Canvas />
      <A11yAnnouncer />
    </>
  )
}
```

### Then wrap components you want to make accessible with the A11y component

To add accessibility features to your scene you'll have to wrap components you want to make focusable with the `A11y` component:

```jsx
import { A11y } from '@react-three/a11y'
[...]
<A11y>
  <MyComponent />
</A11y>
```

`MyComponent` can now receive focus. More accurately, the emulated "focus" will be handled at the `A11y` components which acts as a provider
for children to access its state. But even if objects are focusable, nothing will be displayed or shown by default.

## Call function on focus

The `focusCall` prop of `A11y` will be called each time this component receives focus (usually through tab navigation).

```jsx
<A11y role="content" focusCall={()=> console.log("in focus")} ... />
```

## Call function on click / keyboard Click

The `actionCall` prop of `A11y` will be called each time this component gets clicked, focused, keyboard activated etc.

```jsx
<A11y role="button" actionCall={()=> console.log("clicked")} ... />
```

## Provide a description of the currently focused / hovered element

When using the `description` prop in combination with the `role` prop, the `A11y` component will provide a description to the screen reader users on focus/hover.
Optionally, you can also show the description to the user on hover by setting `showAltText={true}`.

```jsx
// Reads "A rotating red square" to screen readers on focus / hover while also showing it on mouseover
<A11y role="content" description="A rotating red square" showAltText ... />
// Reads "Button, open menu + (description on how to activate depending on the screen reader)" to screen readers on focus / hover
<A11y role="button" description="open menu" actionCall={()=>{someFunction()}} ... />
```

## The four roles of the A11y component

Like in HTML, you can focus different kind of elements and expect different things depending on what you're focusing.

#### Content

```jsx
<A11y role="content" ... />
```

Uses the `default` cursor. This role is meant to provide information to screen readers or to serve as a step for a user to navigate your site using Tab for instance. It's not meant to trigger anything on click or to be activable with the Keyboard. Therefore it won't show a pointer cursor on hover.

[Read more about role content](/a11y/roles/content)

#### Button

```jsx
<A11y
  role="button"
  description="Send email"
  activationMsg="Sending email" ... />
```

Uses the `pointer` cursor. Special attributes: `activationMsg`.

This role is meant to emulate the behaviour of a button or a toggleable button. It will display a cursor pointer when your cursor is over the linked 3D object. It will call a function on click but also on any kind of action that would trigger a focused button (Enter, Double-Tap, ...). It is also actionable by user using a screen reader.

[Read more about role button](/a11y/roles/button)

#### ToggleButton

By using the role togglebutton, you'll emulate a button with two state that will have the `aria-pressed` attribute.
You'll then be able to use the deactivationMsg property in addition to the usual description and activationMsg properties.

```jsx
<A11y
  role="togglebutton"
  description="Dark theme "
  activationMsg="Switched to dark theme"
  deactivationMsg="Switched to light theme" ... />
```

Special attributes: `deactivationMsg`

[Read more about role ToggleButton](/a11y/roles/togglebutton)

#### Link

```jsx
<A11y role="link" href="https://url.com" ... />
```

Uses the `pointer` cursor. Special attributes: `href`.

This role is meant to emulate the behaviour of a regular html link. It should be used in combination with something that will trigger navigation on click.

<Hint>
  - Don't forget to provide the href attribute as it is required for screen readers to read it
  correctly! - It will have no effect on the navigation, it's just used as information
</Hint>

[Read more about role link](/a11y/roles/link)

## Screen Reader Support

In order to provide informations to screen reader users and use this package at its full potential, fill the `description` prop of all your `A11y` components and use the appropriate `role` prop on each of them.

### Use of section

For screen readers, it might be useful to provide additional information on how to use some unconventional UI.
You can do it by wrapping the concerned part of your code relative to this UI in the A11ySection like so.

```jsx
<A11ySection
  label="Shape carousel"
  description="This carousel contains 5 shapes. Use the Previous and Next buttons to cycle through all the shapes."
>
  [...]
</A11ySection>
```

## Access user preferences

The A11yUserPreferences component is available in order to access user preferences such as

- prefers-reduced-motion
- prefers-color-scheme

Take a look at [the A11yUserPreferences page](/a11y/access-user-preferences) or the [demo](https://n4rzi.csb.app) to see it in action and how to use it. The demo will adapt to your system preferences.

## Additional Features

Use a custom tabindex with for your A11y components by providing a number to the tabIndex attribute

```jsx
<A11y tabIndex={-1} ... />
```

<Hint>
  ⚠⚠⚠
  <br />
  Avoid using tabindex values greater than 0. Doing so makes it difficult for people who rely on
  assistive technology to navigate and operate page content. Instead, write the document with the
  elements in a logical sequence.
  <br />
  More about the use of tabIndex on{' '}
  <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex">
    developer.mozilla.org
  </a>
</Hint>


Quick start about how to make your WebGL accessible with @react-three/a11y and react-three-fiber


<p align="center">
  <img width="500" src="/zustand-resources/bear.png" />
</p>
A small, fast and scalable bearbones state-management solution. Has a comfy api based on hooks, isn't
boilerplatey or opinionated, but still just enough to be explicit and flux-like.

Don't disregard it because it's cute. It has quite the claws, lots of time was spent to deal with common pitfalls, like the dreaded [zombie child problem](https://react-redux.js.org/api/hooks#stale-props-and-zombie-children), [react concurrency](https://github.com/bvaughn/rfcs/blob/useMutableSource/text/0000-use-mutable-source.md), and [context loss](https://github.com/facebook/react/issues/13332) between mixed renderers. It may be the one state-manager in the React space that gets all of these right.

You can try a live demo [here](https://codesandbox.io/s/dazzling-moon-itop4).

```bash
npm install zustand
```

### First create a store

Your store is a hook! You can put anything in it: primitives, objects, functions. The `set` function _merges_ state.

```jsx
import create from 'zustand'

const useStore = create((set) => ({
  bears: 0,
  increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
  removeAllBears: () => set({ bears: 0 }),
}))
```

### Then bind your components, and that's it!

Use the hook anywhere, no providers needed. Select your state and the component will re-render on changes.

```jsx
function BearCounter() {
  const bears = useStore((state) => state.bears)
  return <h1>{bears} around here ...</h1>
}

function Controls() {
  const increasePopulation = useStore((state) => state.increasePopulation)
  return <button onClick={increasePopulation}>one up</button>
}
```

#### Why zustand over react-redux?

- Simple and un-opinionated
- Makes hooks the primary means of consuming state
- Doesn't wrap your app in context providers
- [Can inform components transiently (without causing render)](recipes#transient-updates-for-often-occurring-state-changes)

---



A vignette effect.

```jsx
import { Vignette } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <Vignette
    offset={0.5} // vignette offset
    darkness={0.5} // vignette darkness
    eskil={false} // Eskil's vignette technique
    blendFunction={BlendFunction.NORMAL} // blend mode
  />
)
```

## Example

<Codesandbox id="851sn" />

## Props

| Name          | Type          | Default              | Description                         |
| ------------- | ------------- | -------------------- | ----------------------------------- |
| eskil         | Boolean       | false                | Enables Eskil's vignette technique. |
| blendFunction | BlendFunction | BlendFunction.NORMAL | The blend function of this effect.  |
| offset        | Number        | 0.5                  | The vignette offset.                |
| darkness      | Number        | 0.5                  | The vignette darkness.              |


Vignette


A tone mapping effect.

```jsx
import { ToneMapping } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <ToneMapping
    blendFunction={BlendFunction.NORMAL} // blend mode
    adaptive={true} // toggle adaptive luminance map usage
    resolution={256} // texture resolution of the luminance map
    middleGrey={0.6} // middle grey factor
    maxLuminance={16.0} // maximum luminance
    averageLuminance={1.0} // average luminance
    adaptationRate={1.0} // luminance adaptation rate
  />
)
```

## Example

<Codesandbox id="fjb06" />

## Props

| Name             | Type          | Default | Description                                                         |
| ---------------- | ------------- | ------- | ------------------------------------------------------------------- |
| resolution       | Number        | 256     | The resolution of the luminance texture. Must be a power of two.    |
| adaptive         | boolean       | true    | Toggle adaptive luminance map usage                                 |
| blendFunction    | BlendFunction |         | The blend function of this effect.                                  |
| middleGrey       | Number        | 0.6     | The middle grey factor.                                             |
| maxLuminance     | Number        | 16      | Maximum luminance                                                   |
| minLuminance     | Number        | 0.01    | The minimum luminance. Prevents very high exposure in dark scenes.  |
| averageLuminance | Number        | 1       | The average luminance. Used for the non-adaptive Reinhard operator. |
| adaptationRate   | Number        | 1       | The luminance adaptation rate.                                      |


ToneMapping


A Screen Space Ambient Occlusion (SSAO) effect.
For high quality visuals use two SSAO effect instances in a row with different radii, one for rough AO and one for fine details.

This effect supports depth-aware upsampling and should be rendered at a lower resolution. The resolution should match that of the downsampled normals and depth. If you intend to render SSAO at full resolution, do not provide a downsampled normalDepthBuffer and make sure to disable depthAwareUpsampling.

```jsx
import { SSAO } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <SSAO
    blendFunction={BlendFunction.MULTIPLY} // blend mode
    samples={30} // amount of samples per pixel (shouldn't be a multiple of the ring count)
    rings={4} // amount of rings in the occlusion sampling pattern
    distanceThreshold={1.0} // global distance threshold at which the occlusion effect starts to fade out. min: 0, max: 1
    distanceFalloff={0.0} // distance falloff. min: 0, max: 1
    rangeThreshold={0.5} // local occlusion range threshold at which the occlusion starts to fade out. min: 0, max: 1
    rangeFalloff={0.1} // occlusion range falloff. min: 0, max: 1
    luminanceInfluence={0.9} // how much the luminance of the scene influences the ambient occlusion
    radius={20} // occlusion sampling radius
    scale={0.5} // scale of the ambient occlusion
    bias={0.5} // occlusion bias
  />
)
```

## Props

<table class="params">
  <thead>
    <tr>
      <td>Name</td>
      <td>Type</td>
      <td>Default</td>
      <td>Description</td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>blendFunction</td>
      <td>
        <a href="https://vanruesc.github.io/postprocessing/public/docs/variable/index.html#static-variable-BlendFunction">
          BlendFunction
        </a>
      </td>
      <td>BlendFunction.MULTIPLY</td>
      <td>The blend function of this effect.</td>
    </tr>
    <tr>
      <td>distanceScaling</td>
      <td>Boolean</td>
      <td>true</td>
      <td>Enables or disables distance-based radius scaling.</td>
    </tr>
    <tr>
      <td>depthAwareUpsampling</td>
      <td>Boolean</td>
      <td>true</td>
      <td>
        Enables or disables depth-aware upsampling. Has no effect if WebGL 2 is not supported.
      </td>
    </tr>
    <tr>
      <td>normalDepthBuffer</td>
      <td>Texture</td>
      <td>null</td>
      <td>
        A texture that contains downsampled scene normals and depth. See
        <a href="https://vanruesc.github.io/postprocessing/public/docs/class/src/passes/DepthDownsamplingPass.js~DepthDownsamplingPass.html">
          DepthDownsamplingPass
        </a>.
      </td>
    </tr>
    <tr>
      <td>samples</td>
      <td>Number</td>
      <td>9</td>
      <td>The amount of samples per pixel. Should not be a multiple of the ring count.</td>
    </tr>
    <tr>
      <td>rings</td>
      <td>Number</td>
      <td>7</td>
      <td>
        The amount of spiral turns in the occlusion sampling pattern. Should be a prime number.
      </td>
    </tr>
    <tr>
      <td>distanceThreshold</td>
      <td>Number</td>
      <td>0.97</td>
      <td>
        A global distance threshold at which the occlusion effect starts to fade out. Range [0.0,
        1.0].
      </td>
    </tr>
    <tr>
      <td>distanceFalloff</td>
      <td>Number</td>
      <td>0.03</td>
      <td>
        The distance falloff. Influences the smoothness of the overall occlusion cutoff. Range [0.0,
        1.0].
      </td>
    </tr>
    <tr>
      <td>rangeThreshold</td>
      <td>Number</td>
      <td>0.0005</td>
      <td>
        A local occlusion range threshold at which the occlusion starts to fade out. Range [0.0,
        1.0].
      </td>
    </tr>
    <tr>
      <td>rangeFalloff</td>
      <td>Number</td>
      <td>0.001</td>
      <td>
        The occlusion range falloff. Influences the smoothness of the proximity cutoff. Range [0.0,
        1.0].
      </td>
    </tr>
    <tr>
      <td>minRadiusScale</td>
      <td>Number</td>
      <td>0.33</td>
      <td>The minimum radius scale. Has no effect if distance scaling is disabled.</td>
    </tr>
    <tr>
      <td>luminanceInfluence</td>
      <td>Number</td>
      <td>0.7</td>
      <td>Determines how much the luminance of the scene influences the ambient occlusion.</td>
    </tr>
    <tr>
      <td>radius</td>
      <td>Number</td>
      <td>0.1825</td>
      <td>
        The occlusion sampling radius, expressed as a resolution independent scale. Range [1e-6,
        1.0].
      </td>
    </tr>
    <tr>
      <td>intensity</td>
      <td>Number</td>
      <td>1.0</td>
      <td>The intensity of the ambient occlusion.</td>
    </tr>
    <tr>
      <td>bias</td>
      <td>Number</td>
      <td>0.025</td>
      <td>An occlusion bias. Eliminates artifacts caused by depth discontinuities.</td>
    </tr>
    <tr>
      <td>fade</td>
      <td>Number</td>
      <td>0.01</td>
      <td>Influences the smoothness of the shadows. A lower value results in higher contrast.</td>
    </tr>
    <tr>
      <td>color</td>
      <td>Color</td>
      <td>null</td>
      <td>The color of the ambient occlusion.</td>
    </tr>
    <tr>
      <td>resolutionScale</td>
      <td>Number</td>
      <td>1.0</td>
      <td>The resolution scale.</td>
    </tr>
    <tr>
      <td>width</td>
      <td>Number</td>
      <td>Resizer.AUTO_SIZE</td>
      <td>The render width.</td>
    </tr>
    <tr>
      <td>height</td>
      <td>Number</td>
      <td>Resizer.AUTO_SIZE</td>
      <td>The render height.</td>
    </tr>
  </tbody>
</table>


SSAO


Subpixel Morphological Antialiasing (SMAA).

https://github.com/iryoku/smaa/releases/tag/v2.8

By default react-postprocessing uses webgl2 multisampling (MSAA) for native AA. In some effects this can result in artefacts. Should you either want to work with webgl1 exclusively, or you get artefacts, then you can switch MSAA off and use SMAA. This effect is async and relies on suspense!

```jsx
import React, { Suspense } from 'react'
import { EffectComposer, SMAA } from '@react-three/postprocessing'

return (
  <Suspense fallback={null}>
    <EffectComposer multisampling={0}>
      <SMAA />
    </EffectComposer>
  </Suspense>
)
```


SMAA


A sepia effect.

```jsx
import { Sepia } from '@react-three/postprocessing'

return (
  <Sepia
    intensity={1.0} // sepia intensity
    blendFunction={BlendFunction.NORMAL} // blend mode
  />
)
```

## Example

<Codesandbox id="6jyby" />

## Props

| Name          | Type          | Default              | Description                        |
| ------------- | ------------- | -------------------- | ---------------------------------- |
| intensity     | Boolean       | 1                    | The intensity of the effect        |
| blendFunction | BlendFunction | BlendFunction.NORMAL | The blend function of this effect. |


Sepia


A selective bloom effect.

This effect applies bloom to selected objects only.

Attention: If you don't need to limit bloom to a subset of objects, consider using the BloomEffect instead for better performance.

```jsx
import { SelectiveBloom } from '@react-three/postprocessing'
import { BlurPass, Resizer, KernelSize } from 'postprocessing'

return (
  <SelectiveBloom
    lights={[lightRef1, lightRef2]} // ⚠️ REQUIRED! all relevant lights
    selection={[meshRef1, meshRef2]} // selection of objects that will have bloom effect
    selectionLayer={10} // selection layer
    intensity={1.0} // The bloom intensity.
    blurPass={undefined} // A blur pass.
    width={Resizer.AUTO_SIZE} // render width
    height={Resizer.AUTO_SIZE} // render height
    kernelSize={KernelSize.LARGE} // blur kernel size
    luminanceThreshold={0.9} // luminance threshold. Raise this value to mask out darker elements in the scene.
    luminanceSmoothing={0.025} // smoothness of the luminance threshold. Range is [0, 1]
  />
)
```

## Props

| Name               | Type                                                                                                         | Default              | Description                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------- |
| selection          | Objects                                                                                                      |                      | Selection of objects that will be outlined                                                           |
| lights             | Lights                                                                                                       |                      | All lights that will affect the effect                                                               |
| blendFunction      | BlendFunction                                                                                                | BlendFunction.SCREEN | The blend function of this effect.                                                                   |
| width              | Number                                                                                                       | Resizer.AUTO_SIZE    | The render width.                                                                                    |
| height             | Number                                                                                                       | Resizer.AUTO_SIZE    | The render height.                                                                                   |
| selectionLayer     | Number                                                                                                       |                      | The selection layer                                                                                  |
| blurPass           | [BlurPass](https://vanruesc.github.io/postprocessing/public/docs/class/src/passes/BlurPass.js~BlurPass.html) | null                 | An efficient, incremental blur pass.                                                                 |
| kernelSize         | KernelSize                                                                                                   | KernelSize.LARGE     | The blur kernel size.                                                                                |
| luminanceThreshold | Number                                                                                                       | 0.9                  | The luminance threshold. Raise this value to mask out darker elements in the scene. Range is [0, 1]. |
| luminanceSmoothing | Number                                                                                                       | 0.025                | Controls the smoothness of the luminance threshold. Range is [0, 1].                                 |
| intensity          | Number                                                                                                       | 1                    | Intensity of the effect                                                                              |


SelectiveBloom


A scanline effect.

Based on an implementation by Georg 'Leviathan' Steinrohder (CC BY 3.0): http://www.truevision3d.com/forums/showcase/staticnoise_colorblackwhite_scanline_shaders-t18698.0.html

```jsx
import { Scanline } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <Scanline
    blendFunction={BlendFunction.OVERLAY} // blend mode
    density={1.25} // scanline density
  />
)
```

## Example

<Codesandbox id="iy14d" />

## Props

| Name          | Type          | Default               | Description                        |
| ------------- | ------------- | --------------------- | ---------------------------------- |
| density       | Number        | 1.25                  | The scanline density.              |
| blendFunction | BlendFunction | BlendFunction.OVERLAY | The blend function of this effect. |


Scanline


A pixelation effect.

Warning: This effect cannot be merged with convolution effects.

```jsx
import { Pixelation } from '@react-three/postprocessing'

return (
  <Pixelation
    granularity={5} // pixel granularity
  />
)
```

## Example

<Codesandbox id="ed9yo" />

## Props

| Name        | Type   | Default | Description |
| ----------- | ------ | ------- | ----------- |
| granularity | Number | 30      | Pixel Size  |


Pixelation


An outline effect.

```jsx
import { Outline } from '@react-three/postprocessing'
import { BlendFunction, Resizer, KernelSize } from 'postprocessing'

return (
  <Outline
    selection={[meshRef1, meshRef2]} // selection of objects that will be outlined
    selectionLayer={10} // selection layer
    blendFunction={BlendFunction.SCREEN} // set this to BlendFunction.ALPHA for dark outlines
    patternTexture={null} // a pattern texture
    edgeStrength={2.5} // the edge strength
    pulseSpeed={0.0} // a pulse speed. A value of zero disables the pulse effect
    visibleEdgeColor={0xffffff} // the color of visible edges
    hiddenEdgeColor={0x22090a} // the color of hidden edges
    width={Resizer.AUTO_SIZE} // render width
    height={Resizer.AUTO_SIZE} // render height
    kernelSize={KernelSize.LARGE} // blur kernel size
    blur={false} // whether the outline should be blurred
    xRay={true} // indicates whether X-Ray outlines are enabled
  />
)
```

## Props

| Name             | Type          | Default               | Description                                                   |
| ---------------- | ------------- | --------------------- | ------------------------------------------------------------- |
| selection        | Objects       |                       | Selection of objects that will be outlined                    |
| blendFunction    | BlendFunction | BlendFunction.SCREEN  | The blend function of this effect.                            |
| width            | Number        | Resizer.AUTO_SIZE     | The render width.                                             |
| height           | Number        | Resizer.AUTO_SIZE     | The render height.                                            |
| selectionLayer   | Number        |                       | The selection layer                                           |
| patternTexture   | Number        | null                  | A pattern texture                                             |
| edgeStrength     | Number        | 1                     | The edge strength                                             |
| pulseSpeed       | Number        | 0                     | The pulse speed. A value of zero disables the pulse effect.   |
| visibleEdgeColor | Number        | 0xffffff              | The color of visible edges.                                   |
| hiddenEdgeColor  | Number        | 0x22090a              | The color of hidden edges.                                    |
| kernelSize       | KernelSize    | KernelSize.VERY_SMALL | The blur kernel size.                                         |
| blur             | Boolean       | false                 | Whether the outline should be blurred.                        |
| xray             | Boolean       | true                  | Whether occluded parts of selected objects should be visible. |


Outline


A noise effect.

```jsx
import { Noise } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <Noise
    premultiply // enables or disables noise premultiplication
    blendFunction={BlendFunction.ADD} // blend mode
  />
)
```

## Example

<Codesandbox id="8l8hi" />

## Props

| Name          | Type          | Default              | Description                                                  |
| ------------- | ------------- | -------------------- | ------------------------------------------------------------ |
| premultiply   | Boolean       | false                | Whether the noise should be multiplied with the input color. |
| blendFunction | BlendFunction | BlendFunction.SCREEN | The blend function of this effect.                           |


Noise


A hue/saturation effect.

```jsx
import { HueSaturation } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <HueSaturation
    blendFunction={BlendFunction.NORMAL} // blend mode
    hue={0} // hue in radians
    saturation={0} // saturation in radians
  />
)
```

## Example

<Codesandbox id="m9min" />

## Props

| Name          | Type          | Default | Description                        |
| ------------- | ------------- | ------- | ---------------------------------- |
| hue           | Number        | 0       | Hue shift in radians               |
| saturation    | Number        | 0       | Saturation value in radians        |
| blendFunction | BlendFunction |         | The blend function of this effect. |


HueSaturation


A Grid effect

```jsx
import { Grid } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <Grid
    blendFunction={BlendFunction.OVERLAY} // blend mode
    scale={1.0} // grid pattern scale
    lineWidth={0.0} // grid pattern line width
    size={{ width, height }} // overrides the default pass width and height
  />
)
```

## Example

<Codesandbox id="9ebpg" />

## Props

| Name          | Type          | Default              | Description                        |
| ------------- | ------------- | -------------------- | ---------------------------------- |
| blendFunction | BlendFunction | BlendFunction.NORMAL | The blend function of this effect. |
| scale         | Number        | 1                    | The scale of the grid pattern.     |
| lineWidth     | Number        | 0                    | The blend function of this effect. |
| width         | Number        |                      | Overrides the default pass width   |
| height        | Number        |                      | Overrides the default pass height  |


Grid


The GodRays effect requires a mesh that will be used as an origin point for the rays. Refer to this [example](https://github.com/pmndrs/react-postprocessing/tree/2d7edcc2ef7cc2571a86f30ede2b9ee25b38987e/examples/src/demos/TakeControl) for more details.

```jsx
import { GodRays } from '@react-three/postprocessing'

return (
  <GodRays
    sun={sunRef}
    blendFunction={BlendFunction.Screen} // The blend function of this effect.
    samples={60} // The number of samples per pixel.
    density={0.96} // The density of the light rays.
    decay={0.9} // An illumination decay factor.
    weight={0.4} // A light ray weight factor.
    exposure={0.6} // A constant attenuation coefficient.
    clampMax={1} // An upper bound for the saturation of the overall effect.
    width={Resizer.AUTO_SIZE} // Render width.
    height={Resizer.AUTO_SIZE} // Render height.
    kernelSize={KernelSize.SMALL} // The blur kernel size. Has no effect if blur is disabled.
    blur={true} // Whether the god rays should be blurred to reduce artifacts.
  />
)
```

## Props

| Name          | Type                                                                                                               | Default              | Description                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------- | ---------------------------------------------------------------------------- |
| sun           | Ref                                                                                                                |                      | The light source. Must not write depth and has to be flagged as transparent. |
| blendFunction | BlendFunction                                                                                                      | BlendFunction.Screen | The blend function of this effect.                                           |
| samples       | Number                                                                                                             | 60                   | The number of samples per pixel.                                             |
| density       | Number                                                                                                             | 0.96                 | The density of the light rays.                                               |
| decay         | Number                                                                                                             | 0.9                  | An illumination decay factor.                                                |
| weight        | Number                                                                                                             | 0.4                  | A light ray weight factor.                                                   |
| exposure      | Number                                                                                                             | 0.6                  | A constant attenuation coefficient.                                          |
| clampMax      | Number                                                                                                             | 1                    | An upper bound for the saturation of the overall effect.                     |
| width         | Number                                                                                                             | Resizer.AUTO_SIZE    | The render width.                                                            |
| height        | Number                                                                                                             | Resizer.AUTO_SIZE    | The render height.                                                           |
| kernelSize    | [KernelSize](https://vanruesc.github.io/postprocessing/public/docs/variable/index.html#static-variable-KernelSize) | KernelSize.SMALL     | The blur kernel size. Has no effect if blur is disabled.                     |
| blur          | Boolean                                                                                                            | true                 | Whether the god rays should be blurred to reduce artifacts                   |


GodRays


A glitch effect.

```jsx
import { Glitch } from '@react-three/postprocessing'
import { GlitchMode } from 'postprocessing'

return (
  <Glitch
    delay={[1.5, 3.5]} // min and max glitch delay
    duration={[0.6, 1.0]} // min and max glitch duration
    strength={[0.3, 1.0]} // min and max glitch strength
    mode={GlitchMode.SPORADIC} // glitch mode
    active // turn on/off the effect (switches between "mode" prop and GlitchMode.DISABLED)
    ratio={0.85} // Threshold for strong glitches, 0 - no weak glitches, 1 - no strong glitches.
  />
)
```

## Example

<Codesandbox id="bs1i1" />

## Props

| Name                      | Type          | Default              | Description                                                                               |
| ------------------------- | ------------- | -------------------- | ----------------------------------------------------------------------------------------- |
| active                    | Boolean       | true                 | Turn the effect on and off                                                                |
| blendFunction             | BlendFunction | BlendFunction.NORMAL | The blend function of this effect.                                                        |
| chromaticAberrationOffset | Vector2       |                      | A chromatic aberration offset. If provided, the glitch effect will influence this offset. |
| delay                     | Vector2       |                      | The minimum and maximum delay between glitch activations in seconds.                      |
| duration                  | Vector2       |                      | The minimum and maximum duration of a glitch in seconds.                                  |
| strength                  | Vector2       |                      | The strength of weak and strong glitches.                                                 |
| perturbationMap           | Texture       |                      | A perturbation map. If none is provided, a noise texture will be created.                 |
| dtSize                    | Number        | 64                   | The size of the generated noise map. Will be ignored if a perturbation map is provided.   |
| columns                   | Number        | 0.05                 | The scale of the blocky glitch columns.                                                   |
| ratio                     | Number        | 0.85                 | The threshold for strong glitches.                                                        |


Glitch


A dot screen effect.

```jsx
import { DotScreen } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <DotScreen
    blendFunction={BlendFunction.NORMAL} // blend mode
    angle={Math.PI * 0.5} // angle of the dot pattern
    scale={1.0} // scale of the dot pattern
  />
)
```

## Example

<Codesandbox id="xt3fb" />

## Props

| Name          | Type          | Default              | Description                        |
| ------------- | ------------- | -------------------- | ---------------------------------- |
| angle         | Number        | 1 .57                | The angle of the dot pattern.      |
| blendFunction | BlendFunction | BlendFunction.NORMAL | The blend function of this effect. |
| scale         | Number        | 1 .57                | The scale of the dot pattern.      |


Dot Screen


A depth of field effect.

Based on a graphics study by Adrian Courrèges and an article by Steve Avery: https://www.adriancourreges.com/blog/2016/09/09/doom-2016-graphics-study/ https://pixelmischiefblog.wordpress.com/2016/11/25/bokeh-depth-of-field/

```jsx
import { DepthOfField } from '@react-three/postprocessing'

return (
  <DepthOfField
    focusDistance={0} // where to focus
    focalLength={0.02} // focal length
    bokehScale={2} // bokeh size
  />
)
```

## Example

<Codesandbox id="bu796" />

## Props

| Name          | Type          | Default              | Description                                         |
| ------------- | ------------- | -------------------- | --------------------------------------------------- |
| blendFunction | BlendFunction | BlendFunction.NORMAL | The blend function of this effect.                  |
| focusDistance | Number        | 0                    | The normalized focus distance. Range is [0.0, 1.0]. |
| focalLength   | Number        | 0.1                  | The focal length. Range is [0.0, 1.0].              |
| bokehScale    | Number        | 1.0                  | The scale of the bokeh blur.                        |
| width         | Number        | Resizer.width        | The render width.                                   |
| height        | Number        | Resizer.height       | The render height.                                  |


DepthOfField


A color average effect.

```jsx
import { ColorAverage } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <ColorAverage
    blendFunction={BlendFunction.NORMAL} // blend mode
  />
)
```

## Example

<Codesandbox id="ulsyy" />

## Props

| Name          | Type          | Default              | Description                        |
| ------------- | ------------- | -------------------- | ---------------------------------- |
| blendFunction | BlendFunction | BlendFunction.NORMAL | The blend function of this effect. |


ColorAverage


A chromatic aberration effect.

```jsx
import { ChromaticAberration } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <ChromaticAberration
    blendFunction={BlendFunction.NORMAL} // blend mode
    offset={[0.02, 0.002]} // color offset
  />
)
```

## Example

<Codesandbox id="uoyge" />

## Props

| Name          | Type          | Default              | Description                        |
| ------------- | ------------- | -------------------- | ---------------------------------- |
| offset        | Vector2       |                      | The color offset.                  |
| blendFunction | BlendFunction | BlendFunction.Normal | The blend function of this effect. |


ChromaticAberration


Alter brightness and contrast of your scene

```jsx
import { BrightnessContrast } from '@react-three/postprocessing'

return (
  <BrightnessContrast
    brightness={0} // brightness. min: -1, max: 1
    contrast={0} // contrast: min -1, max: 1
  />
)
```

## Example

<Codesandbox id="rrev1" />

## Props

| Name       | Type   | Default | Description            |
| ---------- | ------ | ------- | ---------------------- |
| brightness | Number | 0       | Scene brightness shift |
| contrast   | Number | 0       | Scene contrast shift   |


BrightnessContrast


A bloom effect.

```jsx
import { Bloom } from '@react-three/postprocessing'
import { BlurPass, Resizer, KernelSize } from 'postprocessing'

return (
  <Bloom
    intensity={1.0} // The bloom intensity.
    blurPass={undefined} // A blur pass.
    width={Resizer.AUTO_SIZE} // render width
    height={Resizer.AUTO_SIZE} // render height
    kernelSize={KernelSize.LARGE} // blur kernel size
    luminanceThreshold={0.9} // luminance threshold. Raise this value to mask out darker elements in the scene.
    luminanceSmoothing={0.025} // smoothness of the luminance threshold. Range is [0, 1]
  />
)
```

## Example

<Codesandbox id="r9ujf" />

## Props

| Name               | Type                                                                                                         | Default              | Description                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------- |
| luminanceThreshold | Number                                                                                                       | 0.9                  | The luminance threshold. Raise this value to mask out darker elements in the scene. Range is [0, 1]. |
| luminanceSmoothing | Number                                                                                                       | 0.025                | Controls the smoothness of the luminance threshold. Range is [0, 1].                                 |
| blendFunction      | BlendFunction                                                                                                | BlendFunction.SCREEN | The blend function of this effect.                                                                   |
| intensity          | Number                                                                                                       | 1                    | The intensity.                                                                                       |
| width              | Number                                                                                                       | Resizer.AUTO_SIZE    | The render width.                                                                                    |
| height             | Number                                                                                                       | Resizer.AUTO_SIZE    | The render height.                                                                                   |
| kernelSize         | Number                                                                                                       | KernelSize.LARGE     | The blur kernel size.                                                                                |
| blurPass           | [BlurPass](https://vanruesc.github.io/postprocessing/public/docs/class/src/passes/BlurPass.js~BlurPass.html) | null                 | An efficient, incremental blur pass.                                                                 |


Bloom

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

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


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

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

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


## Fetching everything

You can, but bear in mind that it will cause the component to update on every state change!

```jsx
const state = useStore()
```

## Selecting multiple state slices

It detects changes with strict-equality (old === new) by default, this is efficient for atomic state picks.

```jsx
const nuts = useStore((state) => state.nuts)
const honey = useStore((state) => state.honey)
```

For more control over re-rendering, you may provide an alternative equality function on the second argument.

```jsx
const treats = useStore(
  (state) => state.treats,
  (oldTreats, newTreats) => compare(oldTreats, newTreats)
)
```

For instance, if you want to construct a single object with multiple state-picks inside, similar to redux's mapStateToProps, you can tell zustand that you want the object to be diffed shallowly by passing the `shallow` equality function.

```jsx
import shallow from 'zustand/shallow'

// Object pick, re-renders the component when either state.nuts or state.honey change
const { nuts, honey } = useStore((state) => ({ nuts: state.nuts, honey: state.honey }), shallow)

// Array pick, re-renders the component when either state.nuts or state.honey change
const [nuts, honey] = useStore((state) => [state.nuts, state.honey], shallow)

// Mapped picks, re-renders the component when state.treats changes in order, count or keys
const treats = useStore((state) => Object.keys(state.treats), shallow)
```

## Fetching from multiple stores

Since you can create as many stores as you like, forwarding results to succeeding selectors is as natural as it gets.

```jsx
const currentBear = useCredentialsStore((state) => state.currentBear)
const bear = useBearStore((state) => state.bears[currentBear])
```

## Memoizing selectors

It is generally recommended to memoize selectors with useCallback. This will prevent unnecessary computations each render. It also allows React to optimize performance in concurrent mode.

```jsx
const fruit = useStore(useCallback((state) => state.fruits[id], [id]))
```

If a selector doesn't depend on scope, you can define it outside the render function to obtain a fixed reference without useCallback.

```jsx
const selector = state => state.berries

function Component() {
  const berries = useStore(selector)
```

## Overwriting state

The `set` function has a second argument, `false` by default. Instead of merging, it will replace the state model. Be careful not to wipe out parts you rely on, like actions.

```jsx
import omit from 'lodash-es/omit'

const useStore = create((set) => ({
  salmon: 1,
  tuna: 2,
  deleteEverything: () => set({}, true), // clears the entire store, actions included
  deleteTuna: () => set((state) => omit(state, ['tuna']), true),
}))
```

## Async actions

Just call `set` when you're ready, zustand doesn't care if your actions are async or not.

```jsx
const useStore = create((set) => ({
  fishies: {},
  fetch: async (pond) => {
    const response = await fetch(pond)
    set({ fishies: await response.json() })
  },
}))
```

## Read from state in actions

`set` allows fn-updates `set(state => result)`, but you still have access to state outside of it through `get`.

```jsx
const useStore = create((set, get) => ({
  sound: "grunt",
  action: () => {
    const sound = get().sound
    // ...
  }
})
```

## Reading/writing state and reacting to changes outside of components

Sometimes you need to access state in a non-reactive way, or act upon the store. For these cases the resulting hook has utility functions attached to its prototype.

```jsx
const useStore = create(() => ({ paw: true, snout: true, fur: true }))

// Getting non-reactive fresh state
const paw = useStore.getState().paw
// Listening to all changes, fires on every change
const unsub1 = useStore.subscribe(console.log)
// Listening to selected changes, in this case when "paw" changes
const unsub2 = useStore.subscribe(console.log, state => state.paw)
// Subscribe also supports an optional equality function
const unsub3 = useStore.subscribe(console.log, state => [state.paw, state.fur], shallow)
// Subscribe also exposes the previous value
const unsub4 = useStore.subscribe((paw, previousPaw) => console.log(paw, previousPaw), state => state.paw)
// Updating state, will trigger listeners
useStore.setState({ paw: false })
// Unsubscribe listeners
unsub1()
unsub2()
unsub3()
unsub4()
// Destroying the store (removing all listeners)
useStore.destroy()

// You can of course use the hook as you always would
function Component() {
  const paw = useStore(state => state.paw)
```

## Using zustand without React

Zustands core can be imported and used without the React dependency. The only difference is that the create function does not return a hook, but the api utilities.

```jsx
import create from 'zustand/vanilla'

const store = create(() => ({ ... }))
const { getState, setState, subscribe, destroy } = store
```

You can even consume an existing vanilla store with React:

```jsx
import create from 'zustand'
import vanillaStore from './vanillaStore'

const useStore = create(vanillaStore)
```

## Transient updates (for often occurring state-changes)

The subscribe function allows components to bind to a state-portion without forcing re-render on changes. Best combine it with useEffect for automatic unsubscribe on unmount. This can make a [drastic](https://codesandbox.io/s/peaceful-johnson-txtws) performance impact when you are allowed to mutate the view directly.

```jsx
const useStore = create(set => ({ scratches: 0, ... }))

function Component() {
  // Fetch initial state
  const scratchRef = useRef(useStore.getState().scratches)
  // Connect to the store on mount, disconnect on unmount, catch state-changes in a reference
  useEffect(() => useStore.subscribe(
    scratches => (scratchRef.current = scratches),
    state => state.scratches
  ), [])
```

## Sick of reducers and changing nested state? Use Immer!

Reducing nested structures is tiresome. Have you tried [immer](https://github.com/mweststrate/immer)?

```jsx
import produce from 'immer'

const useStore = create((set) => ({
  lush: { forest: { contains: { a: 'bear' } } },
  set: (fn) => set(produce(fn)),
}))

const set = useStore((state) => state.set)
set((state) => {
  state.lush.forest.contains = null
})
```

## Middleware

You can functionally compose your store any way you like.

```jsx
// Log every time state is changed
const log = (config) => (set, get, api) =>
  config(
    (args) => {
      console.log('  applying', args)
      set(args)
      console.log('  new state', get())
    },
    get,
    api
  )

// Turn the set method into an immer proxy
const immer = (config) => (set, get, api) => config((fn) => set(produce(fn)), get, api)

const useStore = create(
  log(
    immer((set) => ({
      bees: false,
      setBees: (input) => set((state) => void (state.bees = input)),
    }))
  )
)
```

<details>
<summary>How to pipe middlewares</summary>

```js
import create from 'zustand'
import produce from 'immer'
import pipe from 'ramda/es/pipe'

/* log and immer functions from previous example */
/* you can pipe as many middlewares as you want */
const createStore = pipe(log, immer, create)

const useStore = createStore((set) => ({
  bears: 1,
  increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
}))

export default useStore
```

For a TS example see the following [discussion](https://github.com/pmndrs/zustand/discussions/224#discussioncomment-118208)

</details>

<details>
<summary>How to type immer middleware in TypeScript</summary>

```ts
import { State, StateCreator } from 'zustand'
import produce, { Draft } from 'immer'

// Immer V8 or lower
const immer =
  <T extends State>(
    config: StateCreator<T, (fn: (draft: Draft<T>) => void) => void>
  ): StateCreator<T> =>
  (set, get, api) =>
    config((fn) => set(produce(fn) as (state: T) => T), get, api)

// Immer V9
const immer =
  <T extends State>(
    config: StateCreator<T, (fn: (draft: Draft<T>) => void) => void>
  ): StateCreator<T> =>
  (set, get, api) =>
    config((fn) => set(produce<T>(fn)), get, api)
```

</details>

## Persist middleware

You can persist your store's data using any kind of storage.

```jsx
import create from 'zustand'
import { persist } from 'zustand/middleware'

export const useStore = create(
  persist(
    (set, get) => ({
      fishes: 0,
      addAFish: () => set({ fish: get().fish + 1 }),
    }),
    {
      name: 'food-storage', // unique name
      getStorage: () => sessionStorage, // (optional) by default the 'localStorage' is used
    }
  )
)
```

## Can't live without redux-like reducers and action types?

```jsx
const types = { increase: 'INCREASE', decrease: 'DECREASE' }

const reducer = (state, { type, by = 1 }) => {
  switch (type) {
    case types.increase:
      return { grumpiness: state.grumpiness + by }
    case types.decrease:
      return { grumpiness: state.grumpiness - by }
  }
}

const useStore = create((set) => ({
  grumpiness: 0,
  dispatch: (args) => set((state) => reducer(state, args)),
}))

const dispatch = useStore((state) => state.dispatch)
dispatch({ type: types.increase, by: 2 })
```

Or, just use our redux-middleware. It wires up your main-reducer, sets initial state, and adds a dispatch function to the state itself and the vanilla api. Try [this](https://codesandbox.io/s/amazing-kepler-swxol) example.

```jsx
import { redux } from 'zustand/middleware'

const useStore = create(redux(reducer, initialState))
```

## Calling actions outside a React event handler

Because React handles `setState` synchronously if it's called outside an event handler. Updating the state outside an event handler will force react to update the components synchronously, therefore adding the risk of encountering the zombie-child effect.
In order to fix this, the action needs to be wrapped in `unstable_batchedUpdates`

```jsx
import { unstable_batchedUpdates } from 'react-dom' // or 'react-native'

const useStore = create((set) => ({
  fishes: 0,
  increaseFishes: () => set((prev) => ({ fishes: prev.fishes + 1 })),
}))

const nonReactCallback = () => {
  unstable_batchedUpdates(() => {
    useStore.getState().increaseFishes()
  })
}
```

More details: https://github.com/pmndrs/zustand/issues/302

## Redux devtools

```jsx
import { devtools } from 'zustand/middleware'

// Usage with a plain action store, it will log actions as "setState"
const useStore = create(devtools(store))
// Usage with a redux store, it will log full action types
const useStore = create(devtools(redux(reducer, initialState)))
```

devtools takes the store function as its first argument, optionally you can name the store with a second argument: `devtools(store, "MyStore")`, which will be prefixed to your actions.
devtools will only log actions from each separated store unlike in a typical _combined reducers_ redux store. See an approach to combining stores https://github.com/pmndrs/zustand/issues/163

## TypeScript

```tsx
type State = {
  bears: number
  increase: (by: number) => void
}

const useStore = create<State>((set) => ({
  bears: 0,
  increase: (by) => set((state) => ({ bears: state.bears + by })),
}))
```

You can also use an `interface`:

```tsx
import { State } from 'zustand'

interface BearState extends State {
  bears: number
  increase: (by: number) => void
}
```

Or, use `combine` and let tsc infer types.

```tsx
import { combine } from 'zustand/middleware'

const useStore = create(
  combine({ bears: 0 }, (set) => ({
    increase: (by: number) => set((state) => ({ bears: state.bears + by })),
  }))
)
```


Recipes


If you plan to use custom effects, make sure to expose the effect itself as a primitive!

```jsx
import React, { forwardRef, useMemo } from 'react'
import { PixelationEffect } from 'postprocessing'

export const Pixelation = forwardRef(({ granularity = 5 }, ref) => {
  const effect = useMemo(() => new PixelationEffect(granularity), [granularity])
  return <primitive ref={ref} object={effect} dispose={null} />
})
```

For effects that aren't present in `postprocessing` you should extend the `Effect` class:

```js
import React, { forwardRef, useMemo } from 'react'
import { Uniform } from 'three'
import { Effect } from 'postprocessing'

const fragmentShader = `some_shader_code`

let _uParam

// Effect implementation
class MyCustomEffectImpl extends Effect {
  constructor({ param = 0.1 } = {}) {
    super('MyCustomEffect', fragmentShader, {
      uniforms: new Map([['param', new Uniform(param)]]),
    })

    _uParam = param
  }

  update(renderer, inputBuffer, deltaTime) {
    this.uniforms.get('param').value = _uParam
  }
}

// Effect component
export const MyCustomEffect = forwardRef(({ param }, ref) => {
  const effect = useMemo(() => new MyCustomEffectImpl(param), [param])
  return <primitive ref={ref} object={effect} dispose={null} />
})
```


Custom effects


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


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


A [`THREE.CubeCamera`](https://threejs.org/docs/index.html#api/en/cameras/CubeCamera) that returns its texture as a render-prop. It makes children invisible while rendering to the internal buffer so that they are not included in the reflection.

Using the `frames` prop you can control if this camera renders indefinitively or statically (a given number of times).
If you have two static objects in the scene, make it `frames={2}` for instance, so that both objects get to "see" one another in the reflections, which takes multiple renders.
If you have moving objects, unset the prop and use a smaller `resolution` instead.

```jsx
import { CubeCamera } from '@react-three/drei'
;<CubeCamera
  resolution={256} // Size of the off-buffer (256 by default)
  frames={Infinity} // How many frames it should render (Indefinitively by default)
  fog={customFog} // Allows you to pass a Fog or FogExp2 instance for a smaller frustrum
  near={1}
  far={1000}
>
  {(texture) => (
    <mesh>
      <sphereGeometry />
      <meshStandardMaterial envMap={texture} />
    </mesh>
  )}
</CubeCamera>
```

<StoryBook lib="drei" id="camera-cubecamera--default-story" />


CubeCamera


When it comes to accessibility, some users might need to have an interface as still as possible or with a preferred color scheme.

These are CSS media features and this library expose two of them

1. [prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
1. [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion)

While you don't necessarily require this library to access them, we provide an easy way to use them and listen to their changes.

## Setup

For that wrap your components inside the A11yUserPreferences component

```jsx
<A11yUserPreferences>
  <My3dObject />
  <MySecond3dObject />
  [...]
</A11yUserPreferences>
```

Then, you can access the preferences in each children component where you might need them.

## Reduce motions / animations for the users that request it

Some user on your website might need all animation turned off or limited to what's strictly necessary.
For those users, if your app has an animation going somewhere, consider cancelling it for those who request it.
You can do it like so.

```jsx
const My3dObject = () => {
  // this const will give you access to the user preferences
  const { a11yPrefersState } = useUserPreferences()
  const mesh = useRef()

  // Rotate mesh every frame
  useFrame(() => {
    //unless the user prefers reduced motion
    if (!a11yPrefersState.prefersReducedMotion) {
      mesh.current.rotation.x = mesh.current.rotation.y += 0.01
    }
  })

  return (
    <mesh ref={mesh}>
      <boxBufferGeometry args={[1, 1, 1]} />
      <meshStandardMaterial />
    </mesh>
  )
}
```

## Adapt colour scheme depending on the user preference

Some user on your website might need a darker / lighter theme. You can adapt your components according to it like so.

```jsx
const My3dObject = () => {
  // this const will give you access to the user preferences
  const { a11yPrefersState } = useUserPreferences()
  const mesh = useRef()

  return (
    <mesh ref={mesh}>
      <boxBufferGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color={a11yPrefersState.prefersDarkScheme ? 'darkblue' : 'lightblue'} />
    </mesh>
  )
}
```

## Use the context outside and inside the r3f canvas

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 react-dom use the A11yUserPreferences provider, you will not be able to consume it within `<Canvas>`.

There's 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.

You can see how it's used in the [react-three-a11y demo](https://n4rzi.csb.app)


Learn how to access user preferences and how to adjust your app using react-three-fiber with @react-three-a11y

User Preferences


## Resetting state between tests

When running tests, the stores are not automatically reset before each test run.

Thus, there can be cases where the state of one test can affect another. To make sure all tests run with a pristine store state, you can mock `zustand` during testing and replace it with the following code:

```jsx
import actualCreate from 'zustand'
import { act } from 'react-dom/test-utils'

// a variable to hold reset functions for all stores declared in the app
const storeResetFns = new Set()

// when creating a store, we get its initial state, create a reset function and add it in the set
const create = (createState) => {
  const store = actualCreate(createState)
  const initialState = store.getState()
  storeResetFns.add(() => store.setState(initialState, true))
  return store
}

// Reset all stores after each test run
afterEach(() => {
  act(() => storeResetFns.forEach((resetFn) => resetFn()))
})

export default create
```

The way you can mock a dependency depends on your test runner.

In [jest](https://jestjs.io/), you can create a `__mocks__/zustand.js` and place the code there. If your app is using `zustand/vanilla` instead of `zustand`, then you'll have to place the above code in `__mocks__/zustand/vanilla.js`


Testing


## Showcase

<Grid cols={1}>
  <li>
    <Sandbox id="kheke" />
  </li>
</Grid>
<Grid cols={2}>
  <li>
    <Sandbox id="qyz5r" />
  </li>
  <li>
    <Sandbox id="2ij9u" />
  </li>
  <li>
    <Sandbox id="l4klb" />
  </li>
  <li>
    <Sandbox id="kv7tv" />
  </li>
</Grid>
<Grid cols={4}>
  <li>
    <Sandbox id="4m0d0" />
  </li>
  <li>
    <Sandbox id="ls503" />
  </li>
  <li>
    <Sandbox id="n60qg" />
  </li>
  <li>
    <Sandbox id="gsm1y" />
  </li>
  <li>
    <Sandbox id="x8gvs" />
  </li>
  <li>
    <Sandbox id="yjhzv" />
  </li>
  <li>
    <Sandbox id="4jr4p" />
  </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


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


A responsive [THREE.OrthographicCamera](https://threejs.org/docs/index.html#api/en/cameras/OrthographicCamera) that can set itself as the default.

```jsx
import { OrthographicCamera } from '@react-three/drei'
;<OrthographicCamera
  makeDefault // Registers it as the default camera system-wide (default=false)
  {...props} // All THREE.OrthographicCamera props are valid
>
  <mesh />
</OrthographicCamera>
```

<StoryBook lib="drei" id="camera-orthographiccamera--orthographic-camera-scene-st" />


OrthographicCamera


## Role Content of the A11y component

This is the simplest role of all.
You should think of it as the equivalent of an image alt attribute
Whenever you have something in your canvas that is not simply decorative, you should use this role.

Imagine you're displaying some text with the [three.js TextGeometry](https://threejs.org/docs/#api/en/geometries/TextGeometry)

A user using a screen reader would not have access to the text.

Let's say the text is 'Welcome to my website', you could simply do as below.

```jsx
<A11y role="content" description="Welcome to my website">
  <Some3DComponentShowingText />
</A11y>
```

That's it !

Now if you inspect the dom of your app, you will see that a `<p>` tag has been added with your text inside.
That way, user with a screenreader will be able to read that text too.

<Hint>
  For people using screen readers it will also sync some kind of focus indicator natively where your
  text is so people so screen readers users will know where they're currently in your page.
</Hint>

This role can also be used to serve as a step for a user to navigate your site using Tab for instance.
For that you would need to add the tabIndex prop and the focusCall prop like so.

```jsx
<A11y
  role="content"
  description="The second text of my site"
  tabIndex={0}
  focusCall={() => someFunction()}
>
  <SomeOther3DComponentWithText />
</A11y>
```

On focus, you could rotate the camera to show that second piece of text that would usually have required some scrolling to display.
Use it as you please but keep in mind how it might impact the accessibility.
For this example, screenreader don't trigger focus when swiping their screen so it would benefit people used to navigate through keyboard without hurting screenreader users.

It's not meant to trigger anything on click or to be activable with the Keyboard. Therefore it won't show a pointer cursor on hover.


This page will tell you all you need to know about making your content accessible in your react-three-fiber app with @react-three-a11y

Content


Zustand provides bear necessities for state management which is great for most projects; however, some users wish to extend the library's feature set. This can be done using 3rd-party libraries created by the community.

> Disclaimer: These libraries may have bugs, limited maintenance, or other limitations and are not officially recommended by pmndrs or the zustand maintainers. This list is to provide a good starting point for someone looking to extend zustand's feature set.

- [zustand-persist](https://github.com/roadmanfong/zustand-persist) - Persist and rehydrate state
- [simple-zustand-devtools](https://github.com/beerose/simple-zustand-devtools) - Inspect your zustand store in React DevTools 🐻⚛️
- [zustand-store-addons](https://github.com/Diablow/zustand-store-addons) - React state management addons for zustand.
- [zustand-yjs](https://github.com/tandem-pt/zustand-yjs) - Zustand stores for Yjs structures.
- [zustand-forms](https://github.com/Conduct/zustand-forms) - fast typesafe form states as zustand stores
- [zusteller](https://github.com/timkindberg/zusteller) - Your global state savior. "Just hooks" + zustand.
- [geschichte](https://github.com/BowlingX/geschichte) - zustand and immer based hook to manage query parameters
- [zoov](https://github.com/InfiniteXyy/zoov) - Use 🐻 Zustand with Module-like api
- [mobz](https://github.com/2A5F/Mobz) - zustand style mobx api
- [zustand-saga](https://github.com/Nowsta/zustand-saga) - Zustand middleware for redux-saga (minus redux)
- [zundo](https://github.com/charkour/zundo) - 🍜 enable time-travel in your apps. undo/redo middleware for zustand
- [zustand-middleware-computed-state](https://github.com/cmlarsen/zustand-middleware-computed-state) - This is a dead simple middleware for adding computed state to state management library Zustand.
- [shared-zustand](https://github.com/Tom-Julux/shared-zustand) - cross-tab state sharing for zustand


3rd Party Libraries


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
[juggle/resize-observer](https://github.com/juggle/resize-observer).

</Hint>


The Canvas object is your portal into three.js.

Canvas


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


A responsive [THREE.PerspectiveCamera](https://threejs.org/docs/index.html#api/en/cameras/PerspectiveCamera) that can set itself as the default.

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

<PerspectiveCamera
  makeDefault // Registers it as the default camera system-wide (default=false)
  {...props} // All THREE.PerspectiveCamera props are valid
/>
<mesh />
```

You can also give it children, which will now occupy the same position as the camera and follow along as it moves.

```jsx
import { PerspectiveCamera } from '@react-three/drei'
;<PerspectiveCamera makeDefault {...props}>
  <mesh />
</PerspectiveCamera>
```

You can also drive it manually, it won't be responsive and you have to calculate aspect ration yourself.

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

<PerspectiveCamera manual aspect={...} onUpdate={(c) => c.updateProjectionMatrix()}>
```

<StoryBook lib="drei" id="camera-perspectivecamera--perspective-camera-scene-st" />


PerspectiveCamera


## Role Button of the A11y component

This role is meant to emulate the behaviour of a button.
It will display a cursor pointer when your cursor is over the linked 3D object.
It will call a function on click but also on any kind of action that would trigger a focused button (Enter, Double-Tap, ...).
It is also actionnable by user using a screen reader.

```jsx
<A11y
  role="button"
  description="Send email"
  activationMsg="Sending email"
  actionCall={()=>sendEmail()}
  ... >
  <Some3DComponent />
</A11y>
```

Using it like this makes it focusable to all kind of users.

You should also use the useA11y() hook within the encapsulated components to adjust the rendering on hover and focus. Doing so greatly improve the accessibility of your page.
Take a look at this code sample to see how to use it.
You can also play with it in [this demo](https://n4rzi.csb.app)

```jsx
function Some3DComponent() {
  const a11y = useA11y()
  return (
    <mesh>
      <boxBufferGeometry />
      <meshStandardMaterial
        metalness={1}
        roughness={0.8}
        color={a11y.focus || a11y.hover ? '#cc66dd' : '#ffffff'}
        emissive={a11y.focus ? '#cc4444' : a11y.hover ? '#339922' : '#003399'}
      />
    </mesh>
  )
}
```

You could also specify the optional prop `activationMsg`.
The message withinh activationMsg will be announced by screenreader when the button is activated.


This page will tell you all you need to know about emulating an accessible button in your react-three-fiber app with @react-three-a11y

Button


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


🚧 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


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 controls](https://github.com/mrdoob/three.js/tree/dev/examples/jsm/controls).

Some controls allow you to set `makeDefault`, similar to, for instance, PerspectiveCamera. This will set react-three-fiber's `controls` field in the root store. This can make it easier in situations where you want controls to be known and other parts of the app could respond to it. Some drei controls already take it into account, like CameraShake, Gizmo and TransformControls.

Drei currently exports `OrbitControls`, `MapControls`, `TrackballControls`, `ArcballControls`, `FlyControls`, `DeviceOrientationControls`, `PointerLockControls`, `FirstPersonControls`

All controls react to the default camera. If you have a `<PerspectiveCamera makeDefault />` in your scene, they will control it. If you need to inject an imperative camera or one that isn't the default, use the `camera` prop: `<OrbitControls camera={MyCamera} />`.

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). All elements matching the `selector` prop will activate the controls.



## Role ToggleButton of the A11y component

This is mostly the same as the [button role](/a11y/roles/button).
The difference is that this button will have the aria-pressed attribute and that you'll be able to use the following deactivationMsg property in addition to the usual description and activationMsg properties.

Since this role is meant to emulate the behaviour of togglable button.
It will display a cursor pointer when your cursor is over the linked 3D object.
It will call a function on click but also on any kind of action that would trigger a focused button (Enter, Double-Tap, ...).
It is also actionnable by user using a screen reader.

```jsx
<A11y
  role="togglebutton"
  description="Dark theme"
  startPressed={false}
  actionCall="()=>switchTheme()"
  ...>
  <Some3DComponent />
</A11y>
```

Using it like this makes it focusable to all kind of users.

<Hint>
  You might have noticed the startPressed prop. Depending on your need, you might want to have your
  button starting in a pressed state. This is what this prop is for.
</Hint>

You should also use the useA11y() hook within the encapsulated components to adjust the rendering on hover and focus and pressed state. Doing so greatly improve the accessibility of your page.
Take a look at this code sample to see how to use it.
You can also play with it in [this demo](https://n4rzi.csb.app)

```jsx
function Some3DComponent() {
  const a11y = useA11y() // access pressed, hover and focus
  return (
    <mesh>
      <boxBufferGeometry />
      <meshStandardMaterial
        metalness={1}
        roughness={0.8}
        color={a11y.focus || a11y.hover ? '#cc66dd' : '#ffffff'}
        emissive={a11y.focus ? '#cc4444' : a11y.hover ? '#339922' : '#003399'}
      />
    </mesh>
  )
}
```

You could also specify the optional prop `activationMsg` and `deactivationMsg`.
Respective message will be announced by screenreader when the button is activated / deactivated.


This page will tell you all you need to know about emulating an accessible togglable button in your react-three-fiber app with @react-three-a11y

ToggleButton


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


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


Can be used to orient the camera based on the mobile device's orientation.

```jsx
import { DeviceOrientationControls } from '@react-three/drei'
;<DeviceOrientationControls />
```

<StoryBook lib="drei" id="controls-deviceorientationcontrols--device-orientation-controls-story" />


DeviceOrientationControls


## Role Link of the A11y component

This role is fairly straightforward
You should think of it as the equivalent of an html link "a" tag
Since it's meant to emulate the behaviour of a regular html link. It should be used in combination with something that will trigger navigation on click.

```jsx
<A11y
  role="link"
  href="/page"
  actionCall={() => {
    router.push(`/page`)
  }}
>
  <Some3DComponent />
</A11y>
```

Using it like this makes it focusable to all kind of users. It will also show a pointer on mouse over.

You should also use the useA11y() hook within the encapsulated components to adjust the rendering on hover and focus. Doing so greatly improve the accessibility of your page.
Take a look at this code sample to see how to use it.
You can also play with it in [this demo](https://n4rzi.csb.app)

```jsx
function Some3DComponent() {
  const a11y = useA11y()
  return (
    <mesh>
      <boxBufferGeometry />
      <meshStandardMaterial
        metalness={1}
        roughness={0.8}
        color={a11y.focus || a11y.hover ? '#cc66dd' : '#ffffff'}
        emissive={a11y.focus ? '#cc4444' : a11y.hover ? '#339922' : '#003399'}
      />
    </mesh>
  )
}
```

<Hint>
  Don't forget to provide the href attribute as he is required for screen readers to read it
  correctly !<br />
  It will have no effect on the navigation, it's just used as information
</Hint>


This page will tell you all you need to know about emulating an accessible link in your react-three-fiber app with @react-three-a11y

Link


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


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


FlyControls enables a navigation similar to fly modes in DCC tools like Blender. You can arbitrarily transform the camera in 3D space without any limitations (e.g. focus on a specific target).

```jsx
import { FlyControls } from '@react-three/drei'
;<FlyControls autoForward={false} dragToLook={false} movementSpeed={1.0} rollSpeed={0.005} />
```

<StoryBook lib="drei" id="controls-flycontrols--fly-controls-story" />


FlyControls


This library is pretty simple, if you're curious about how it works you can read the following information and look at the internals.

@react-three/a11y purpose is to manage the accessibility part of what is inside your canvas by syncing semantic DOM absolutely positioned over what's currently visible in your page.

Basically when you add the A11y component with a role, react-three-a11y will append the corresponding HTML tag to your document.<br />

- role="link" => a
- role="button" => button
- role="content" => p
- role="togglebutton" => button ( + aria-pressed )

The position is synced by a minimalist fork of the [Drei Html component](/drei/misc/html)

Inside an A11y component, you can access the hover, focused and pressed state through the useA11y() hook.
This hook returns the context of the A11y component.

The A11yAnnouncer is used to communicate with screen readers through a div only visible to screen readers.
It uses a [zustand](/zustand) store to update the div with each new message.
The div is roughly like this.

```html
<div aria-atomic="true" aria-live="polite">{message}</div>
```

The A11ySection component appends an HTML section in which a p element describe the content of the section.
Wrapped around some A11y components, it will cause the HTML from those component to be inside the section.

You would then have a generated DOM that could look something like this.

```html
<section aria-label="label">
  <p>description</p>
  <button></button>
  <p></p>
  <button></button>
</section>
```

For the A11yUserPreferences component, it simply exposes through a context the state of prefers-color-scheme and prefers-reduced-motion media queries.
It watches for change through

```javascript
window.matchMedia('(prefers-reduced-motion: reduce)')
window.matchMedia('(prefers-color-scheme: dark)')
```


This is an advanced guide on the inner workings of @react-three/a11y, if you are just getting started, take a look at our introduction!

How does it work?


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

`pointerenter` and `pointerleave` events work exactly the same as pointerover and pointerout.
`pointerenter` and `pointerleave` semantics are not implemented.

</Hint>

<Hint>

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

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


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


Modifications to [`THREE.TrackballControls`](https://threejs.org/docs/?q=TrackballControls#examples/en/controls/TrackballControls), offering camera controls suitable for flat scenes — panning, zooming, and limited rotation.

```jsx
import { MapControls } from '@react-three/drei'
;<MapControls />
```

<StoryBook lib="drei" id="controls-mapcontrols--map-controls-scene-st" />


MapControls


### Position of the accessible dom causing wrong hover detection

In the demo, you may have noticed in App.js that the component ToggleButton is wrapped in an A11y component that use the prop a11yElStyle like so

```jsx
<A11y
  role="togglebutton"
  description="Light intensity"
  actionCall={() => (state.dark = !snap.dark)}
  activationMsg="Lower light disabled"
  deactivationMsg="Lower light enabled"
  a11yElStyle={{ marginLeft: '-40px' }}
>
  <ToggleButton position={[0, -3, 9]} />
</A11y>
```

Why is that ?

In order to make this "donut" accessible as a button react-three-a11y will keep an html button over it.

If we inspect the DOM, you should see something roughly like this for the above example.

```html
<button aria-pressed="false">Light intensity</button>
```

By default this button is positionned in the center of your 3D object which would cause it to work like this.

1- Mouse is not over

<p align="middle">
  <img alt="" height="200" src="/a11y/beforehoverdefault.png" />
</p>

2- Mouse is over the donut, color change is triggered and the cursor pointer is displayed

<p align="middle">
  <img alt="" height="200" src="/a11y/hoverdefaultout.png" />
</p>

3- Mouse is not over the donut, but the color change is still triggered as is the cursor pointer

<p align="middle">
  <img alt="" height="200" src="/a11y/hoverdefault.png" />
</p>

If we display the button we can see that it's caused by the button being positioned in the middle of the donut

<p align="middle">
  <img alt="" height="200" src="/a11y/hoverdefaultbecause.png" />
</p>

4- If we add a11yElStyle={{ marginLeft: '-40px' }} to the A11y component, the button is moved to the left and not in the center of the donut anymore

<p align="middle">
  <img alt="" height="200" src="/a11y/hoverfixbecause.png" />
</p>

5- And as we can see, it fixes our issue. The cursor is default and no color change while the cursor is in the hole of the donut.

<p align="middle">
  <img alt="" height="200" src="/a11y/hoverfix.png" />
</p>


Gotchas


| 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


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


Orbit controls allow the camera to orbit around a target.

```jsx
import { OrbitControls } from '@react-three/drei'
;<OrbitControls enablePan={true} enableZoom={true} enableRotate={true} />
```

<StoryBook lib="drei" id="controls-orbitcontrols--orbit-controls-story" />


OrbitControls


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 `invalidate()` will not render immediately, it merely requests a
new frame to be rendered out. Calling invalidate multiple times will not render multiple times.
Think of it as a flag to tell the system that something has changed.

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

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


The implementation of this class is based on the [Pointer Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API). PointerLockControls is a perfect choice for first person 3D games.

```jsx
import { PointerLockControls } from '@react-three/drei'
;<PointerLockControls />
```

<StoryBook lib="drei" id="controls-pointerlockcontrols--pointer-lock-controls-scene-st" />


PointerLockControls


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


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


Semi-OrbitControls with spring-physics, polar zoom and snap-back, for presentational purposes. These controls do not turn the camera but will spin their contents.

They will not suddenly come to rest when they reach limits like OrbitControls do, but rather smoothly anticipate stopping position.

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

<PresentationControls
  global={false} // Spin globally or by dragging the model
  snap={false} // Snap-back to center (can also be a spring config)
  speed={1} // Speed factor
  zoom={1} // Zoom factor when half the polar-max is reached
  rotation={[0, 0, 0]} // Default rotation
  polar={[0, Math.PI / 2]} // Vertical limits
  azimuth={[-Infinity, Infinity]} // Horizontal limits
  config = { mass: 1, tension: 170, friction: 26 } // Spring config
>
  <mesh />
</PresentationControls>
```

<Grid cols={1}>
  <li>
    <Sandbox id="z0sed" />
  </li>
</Grid>


PresentationalControls


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



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


Scroll controls create a HTML scroll container in front of the canvas. Everything you drop into the `<Scroll>` component will be affected.

You can listen and react to scroll with the `useScroll` hook which gives you useful data like the current scroll `offset`, `delta` and functions for range finding: `range`, `curve` and `visible`. The latter functions are especially useful if you want to react to the scroll offset, for instance if you wanted to fade things in and out if they are in or out of view.

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

<ScrollControls
  pages={3} // Each page takes 100% of the height of the canvas
  distance={1} // A factor that increases scroll bar travel (default: 1)
  damping={4} // Friction, higher is faster (default: 4)
  horizontal={false} // Can also scroll horizontally (default: false)
  infinite={false} // Can also scroll infinitely (default: false)
>
  {/* You can have components in here, they are not scrolled, but they can still
      react to scroll by using useScroll! */}
  <Scroll>
    <Foo position={[0, 0, 0]} />
    <Foo position={[0, viewport.height, 0]} />
    <Foo position={[0, viewport.height * 1, 0]} />
  </Scroll>
  <Scroll html>
    <h1>html in here (optional)</h1>
    <h1 style={{ top: '100vh' }}>second page</h1>
    <h1 style={{ top: '200vh' }}>third page</h1>
  </Scroll>
</ScrollControls>
function Foo() {
  const ref = useRef()
  const data = useScroll()
  useFrame(() => {
    // data.offset = current scroll position, between 0 and 1, dampened
    // data.delta = current delta, between 0 and 1, dampened
    // Will be 0 when the scrollbar is at the starting position,
    // then increase to 1 until 1 / 3 of the scroll distance is reached
    const a = data.range(0, 1 / 3)
    // Will start increasing when 1 / 3 of the scroll distance is reached,
    // and reach 1 when it reaches 2 / 3rds.
    const b = data.range(1 / 3, 1 / 3)
        // Same as above but with a margin of 0.1 on both ends
    const c = data.range(1 / 3, 1 / 3, 0.1)
    // Will move between 0-1-0 for the selected range
    const d = data.curve(1 / 3, 1 / 3)
    // Same as above, but with a margin of 0.1 on both ends
    const d = data.curve(1 / 3, 1 / 3, 0.1)
    // Returns true if the offset is in range and false if it isn't
    const e = data.visible(2 / 3, 1 / 3)
    // The visible function can also receive a margin
    const f = data.visible(2 / 3, 1 / 3, 0.1)
  })
  return <mesh ref={ref} {...props} />
```

<Grid cols={2}>
  <li>
    <Sandbox id="l4klb" />
  </li>
  <li>
    <Sandbox id="4m0d0" />
  </li>
  <li>
    <Sandbox id="gsm1y" />
  </li>
  <li>
    <Sandbox id="x8gvs" />
  </li>
  <li>
    <Sandbox id="yjhzv" />
  </li>
  <li>
    <Sandbox id="4jr4p" />
  </li>
</Grid>


ScrollControls


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


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


`TrackballControls` is similar to `OrbitControls`. However, it does not maintain a constant camera up vector. That means if the camera orbits over the “north” and “south” poles, it does not flip to stay "right side up".

```jsx
import { TrackballControls } from '@react-three/drei'
;<TrackballControls />
```

<StoryBook lib="drei" id="controls-trackballcontrols--trackball-controls-scene-st" />


TrackballControls


> 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


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


An abstraction around [THREE.TransformControls](https://threejs.org/docs/index.html?q=transfor#examples/en/controls/TransformControls).

You can wrap objects which then receive a transform gizmo.

```jsx
import { TransformControls } from '@react-three/drei'
;<TransformControls mode="translate">
  <mesh />
</TransformControls>
```

You could also reference the object which might make it easier to exchange the target. Now the object does not have to be part of the same sub-graph. References can be plain objects or `React.MutableRefObjects`.

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

<TransformControls object={mesh} mode="translate">
<mesh ref={mesh} />
```

If you are using other controls (`OrbitControls`, `TrackballControls`, etc), you will notice how they interfere, dragging one will affect the other. Default-controls will temporarily be disabled automatically when the user is pulling on the transform gizmo.

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

<TransformControls mode="translate" />
<OrbitControls makeDefault />
```

<StoryBook lib="drei" id="controls-transformcontrols--transform-controls-story" />


TransformControls


> 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


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


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


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


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


Renders a [`THREE.Line2`](https://threejs.org/docs/#api/en/objects/Line) using THREE.CubicBezierCurve3 for interpolation.

```jsx
<CubicBezierLine
  start={[0, 0, 0]}               // Starting point
  end={[10, 0, 10]}               // Ending point
  midA={[5, 0, 0]}                // First control point
  midB={[0, 0, 5]}                // Second control point
  color="black"                   // Default
  lineWidth={1}                   // In pixels (default)
  dashed={false}                  // Default
  vertexColors={[[0, 0, 0], ...]} // Optional array of RGB values for each point
  {...lineProps}                  // All THREE.Line2 props are valid
  {...materialProps}              // All THREE.LineMaterial props are valid
/>
```

<StoryBook lib="drei" id="abstractions-line--cubic-bezier" />


CubicBezierLine


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


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


Abstraction around threes own [EffectComposer](https://threejs.org/docs/index.html#examples/en/postprocessing/EffectComposer).

```jsx
<Effects
  multisamping={8} // Default, uses WebGL2 multisamping if available
  renderIndex={1} // Default
  disableGamma={false} // Default, would switch off the gamma-correction-pass
  disableRenderPass={false} // Default, would remove the first scene-render-pass
>
  {/* Generic passes go here ... */}
  <lUTPass attachArray="passes" lut={texture3D} />
</Effects>
```


Effects


This tutorial will assume some React and TypeScript knowledge. You can fork and follow along from [this starter codesandbox](https://codesandbox.io/s/brnsm).

## Typing with useRef

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

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

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

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

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

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

The exclamation mark is a non-null assertion that will let TS know that `ref.current` is defined when we access it in effects.

## Typing shorthand props

react-three-fiber accepts short-hand props like scalars, strings, and arrays so you can declaratively set properties without side effects.

Here are the different variations of props:

```tsx
import { Euler, Vector3, Color } from 'three'

rotation: Euler || [x, y, z]
position: Vector3 || [x, y, z] || scalar
color: Color || 'hotpink' || 0xffffff
```

Each property has extended types which you can pull from to type these properties.

```tsx
import { Euler, Vector3, Color } from '@react-three/fiber'
// or
// import { ReactThreeFiber } from '@react-three/fiber'
// ReactThreeFiber.Euler, ReactThreeFiber.Vector3, etc.

rotation: Euler
position: Vector3
color: Color
```

This is particularly useful if you are typing properties outside of components, such as a store or a hook.

## Extend usage

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

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

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

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

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

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

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

<customElement />
```

### Node Helpers

react-three-fiber exports helpers that you can use to define different types of nodes. These nodes will type an element that we'll attach to the global JSX namespace.

```tsx
Node
Object3DNode
BufferGeometryNode
MaterialNode
LightNode
```

### Extending JSX.IntrinsicElements

Since our custom element is an object, we'll use `Object3DNode` to define it.

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

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

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

// Add types to JSX.Intrinsic elements so primitives pick up on it
declare global {
  namespace JSX {
    interface IntrinsicElements {
      customElement: Object3DNode<CustomElement, typeof CustomElement>
    }
  }
}

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

## Exported types

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

```tsx
// Event raycaster intersection
Intersection

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

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

// Canvas props
Props

// Supported events
Events

// Event manager signature (is completely modular)
EventManager

// Wraps a platform event as it's passed through the event manager
ThreeEvent
```


This guide will help through common scenarios and how to approach them with TypeScript.

Using with TypeScript


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)



Sets up a global cubemap, which affects the default `scene.environment`, and optionally `scene.background`, unless a custom scene has been passed. A selection of [presets](https://github.com/pmndrs/drei/blob/master/src/helpers/environment-assets.ts) from [HDRI Haven](https://hdrihaven.com/) are available for convenience.

```jsx
<Environment
  background={false} // Whether to affect scene.background
  files={['px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png', 'nz.png']} // Array of cubemap files OR single equirectangular file
  path={'/'} // Path to the above file(s)
  preset={null} // Preset string (overrides files and path)
  scene={undefined} // adds the ability to pass a custom THREE.Scene
/>
```

<StoryBook lib="drei" id="abstractions-environment--environment-st" />


Environment


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



Used by widgets that visualize and control camera position.

Two example gizmos are included: GizmoViewport and GizmoViewcube, and `useGizmoContext` makes it easy to create your own.

```jsx
<GizmoHelper
  alignment="bottom-right" // widget alignment within scene
  margin={[80, 80]} // widget margins (X, Y)
  onUpdate={/* called during camera animation  */}
  onTarget={/* return current camera target (e.g. from orbit controls) to center animation */}
>
  <GizmoViewport axisColors={['red', 'green', 'blue']} labelColor="black" />
  {/* alternative: <GizmoViewcube /> */}
</GizmoHelper>
```


GizmoHelper

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

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



## Render Loop

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

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



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

_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!


Renders a [`THREE.Line2`](https://threejs.org/docs/#api/en/objects/Line).

```jsx
<Line
  points={[[0, 0, 0], ...]}       // Array of points
  color="black"                   // Default
  lineWidth={1}                   // In pixels (default)
  dashed={false}                  // Default
  vertexColors={[[0, 0, 0], ...]} // Optional array of RGB values for each point
  {...lineProps}                  // All THREE.Line2 props are valid
  {...materialProps}              // All THREE.LineMaterial props are valid
/>
```

<StoryBook lib="drei" id="abstractions-line--basic-line" />


Line


A wrapper around [`THREE.PositionalAudio`](https://threejs.org/docs/index.html#api/en/audio/PositionalAudio). Add this to groups or meshes to tie them to a sound that plays when the camera comes near.

```jsx
<PositionalAudio
  url="/sound.mp3" // Url of the sound file
  distance={1} // Camera distance (default=1)
  loop // Repat play (default=true)
  {...props} // All THREE.PositionalAudio props are valid
/>
```

<StoryBook lib="drei" id="abstractions-positionalaudio--positional-audio-scene-st" />
