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


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

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

There is no additional overhead. Components participate in the renderloop outside of React.

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

---

### 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_ threejs exports are native to three-fiber.
- Try changing some values, scroll through our [Api](/markdown/api.md) 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 install 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/drcmda/pmndrs/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://wiki.aragon.org/design/logo/svg/imagetype.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>



`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


<p align="center">
  <img src="https://github.com/pmndrs/jotai/raw/master/img/title.svg" alt="jotai" />
</p>

👻 Primitive and flexible state management for React.

`npm install jotai` or `yarn add jotai`

Jotai is pronounced "joe-tie" and means "state" in Japanese.

You can try live demos in the following:
[Demo 1](https://codesandbox.io/s/jotai-demo-47wvh) |
[Demo 2](https://codesandbox.io/s/jotai-demo-forked-x2g5d).

#### How does Jotai differ from Recoil?

- Minimalistic API
- No string keys
- TypeScript oriented

### First create a primitive atom

An atom represents a piece of state. All you need is to specify an initial
value, which can be primitive values like strings and numbers, objects and
arrays. You can create as many primitive atoms as you want.

```jsx
import { atom } from 'jotai'

const countAtom = atom(0)
const countryAtom = atom('Japan')
const citiesAtom = atom(['Tokyo', 'Kyoto', 'Osaka'])
const mangaAtom = atom({ 'Dragon Ball': 1984, 'One Piece': 1997, Naruto: 1999 })
```

### Use the atom in your components

It can be used like `React.useState`:

```jsx
import { useAtom } from 'jotai'

function Counter() {
  const [count, setCount] = useAtom(countAtom)
  return (
    <h1>
      {count}
      <button onClick={() => setCount(c => c + 1)}>one up</button>
```

### Create derived atoms with computed values

A new read-only atom can be created from existing atoms by passing a read
function as the first argument. `get` allows you to fetch the contextual value
of any atom.

```jsx
const doubledCountAtom = atom((get) => get(countAtom) * 2)

function DoubleCounter() {
  const [doubledCount] = useAtom(doubledCountAtom)
  return <h2>{doubledCount}</h2>
```

## Recipes

### Creating an atom from multiple atoms

You can combine multiple atoms to create a derived atom.

```jsx
const count1 = atom(1)
const count2 = atom(2)
const count3 = atom(3)

const sum = atom((get) => get(count1) + get(count2) + get(count3))
```

Or if you like fp patterns ...

```jsx
const atoms = [count1, count2, count3, ...otherAtoms]
const sum = atom((get) => atoms.map(get).reduce((acc, count) => acc + count))
```

### Derived async atoms <img src="https://img.shields.io/badge/-needs_suspense-black" alt="needs suspense" />

You can make the read function an async function too.

```jsx
const urlAtom = atom("https://json.host.com")
const fetchUrlAtom = atom(
  async (get) => {
    const response = await fetch(get(urlAtom))
    return await response.json()
  }
)

function Status() {
  // Re-renders the component after urlAtom changed and the async function above concludes
  const [json] = useAtom(fetchUrlAtom)
```

### You can create a writable derived atom

Specify a write function at the second argument. `get` will return the current
value of an atom. `set` will update an atoms value.

```jsx
const decrementCountAtom = atom(
  (get) => get(countAtom),
  (get, set, _arg) => set(countAtom, get(countAtom) - 1),
)

function Counter() {
  const [count, decrement] = useAtom(decrementCountAtom)
  return (
    <h1>
      {count}
      <button onClick={decrement}>Decrease</button>
```

### Write only atoms

Just do not define a read function.

```jsx
const multiplyCountAtom = atom(null, (get, set, by) => set(countAtom, get(countAtom) * by))

function Controls() {
  const [, multiply] = useAtom(multiplyCountAtom)
  return <button onClick={() => multiply(3)}>triple</button>
```

### Async actions <img src="https://img.shields.io/badge/-needs_suspense-black" alt="needs suspense" />

Just make the write function an async function and call `set` when you're ready.

```jsx
const fetchCountAtom = atom(
  (get) => get(countAtom),
  async (_get, set, url) => {
    const response = await fetch(url)
    set(countAtom, (await response.json()).count)
  }
)

function Controls() {
  const [count, compute] = useAtom(fetchCountAtom)
  return <button onClick={() => compute("http://count.host.com")}>compute</button>
```



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

[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 readears, it might be useful to provide additionnal 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.

## Additionals 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-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 component for applying a configurable camera shake effect. Currently only supports rotational camera shake. Pass a ref to recieve the `ShakeController` API.

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

<CameraShake {...config} />


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

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


CameraShake

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


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!

## 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](/hooks/usespring), 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](/docs/hooks/api). 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](/docs/hooks/api) 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`](/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 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/react-spring/@react-three/postprocessing/tree/master/examples/take-control) 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


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


Jotai was born to solve extra re-render issue in React.
Extra re-render is a render process that produces the same UI result,
with which users won't see any differences.

To tackle this issue naively with React context (useContext + useState),
one would probably require many contexts and face some issues.

- Provider hell: It's likely that your root component has many context providers, which is technically okay, and sometimes desirable to provide context in different subtree.
- Dynamic addition/deletion: Adding a new context at runtime is not very nice, because you need to add a new provider and its children will be re-mounted.

Traditionally, a top-down solution to this is to use selector interface.
The [use-context-selector](https://github.com/dai-shi/use-context-selector) library is one example.
The issue with this approach is the selector function needs to return
referentially equal values to prevent re-renders and often requires some memoization technique.

Jotai takes a bottom-up approach with atomic model, inspired by [Recoil](https://recoiljs.org/).
One can build state combining atoms and renders are optimized based on atom dependency.
This avoids requiring the memoization technique.

Jotai has two principles.

- Primitive: Its basic interface is pretty much like `useState`.
- Flexible: Derived atoms can combine other atoms and also allow `useReducer` style with side effects.

Jotai's core API is minimalistic and allows building various utils based on it.

Check out [comparison doc](/jotai/basics/comparison) to see some differences with other libraries.


Concepts


State in Jotai is a set of atoms.
An atom is a piece of state.
Unlike useState in React, atoms are not tied to specific components.
Let's see how to define and use atoms.

## atom

There's an exported function called `atom`, which is to create
an atom config. We call it "config" as it's just a definition
and it doesn't hold a value. We may just call it "atom" if the context is clear.

To create a primitive atom (config), all you need is pass an initial value.

```js
import { atom } from 'jotai'

const priceAtom = atom(10)
const messageAtom = atom('hello')
const productAtom = atom({ id: 12, name: 'good stuff' })
```

You can also create derived atoms. We have three patterns.

- Read-only atom
- Write-only atom
- Read-Write atom

To create derived atoms, we pass a read function and an optional write function.

```js
const readOnlyAtom = atom((get) => get(priceAtom) * 2)
const writeOnlyAtom = atom(
  null, // it's a convention to pass `null` for the first argument
  (get, set, update) => {
    // `update` is any single value we receive for updating this atom
    set(priceAtom, get(priceAtom) - update.discount)
  }
)
const readWriteAtom = atom(
  (get) => get(priceAtom) * 2,
  (get, set, newPrice) => {
    set(priceAtom, newPrice / 2)
    // you can set as many atoms as you want at the same time
  }
)
```

`get` in the read function is to read the atom value.
It's reactive and read dependencies are tracked.

`get` in the write function is also to read atom value, and it's not tracked.
Furthermore, it can't read unresolved async values.
For async behavior, please refer to the [async](/jotai/basics/async) doc.

`set` in the write function is to write atom value.
It will invoke the write function of the target atom.

Atom configs can be created anywhere, but referential equality is important.
They can be created dynamically too.
To create an atom in render function, `useMemo` or `useRef` is required to get a stable reference. If in doubt about using `useMemo` or `useRef` for memorization, use `useMemo`.

```jsx
const Component = ({ value }) => {
  const valueAtom = useMemo(() => atom({ value }), [value])
  // ...
}
```

## useAtom

The `useAtom` hook is to read an atom value in the state.
The state can be seen as a WeakMap of atom configs and atom values.

The `useAtom` function returns the atom value and an updating function as a tuple,
just like React's `useState`.
It takes an atom config created with `atom()`.

Initially, there is no value stored in the state.
The first time the atom is used via `useAtom`,
the initial value is stored in the state.
If the atom is a derived atom, the read function is executed to compute an initial value.
When an atom is no longer used, meaning all the components using it is unmounted,
and the atom config no longer exists, the value in the state is garbage collected.

```js
const [value, updateValue] = useAtom(anAtom)
```

The `updateValue` takes just one argument, which will be passed
to the third argument of write function of the atom.
The behavior totally depends on how the write function is implemented.

## Provider

Provider is to provide a state for component sub tree.
Multiple Providers can be used for multiple subtrees, even nested.
This works just like the normal React Context.

If an atom is used in a tree which no Providers exist,
it will use the default state. This is so-called provider-less mode.

Providers are useful for some reasons.

1. It can provide a different state for each sub tree.
2. Provider can hold some debug information.
3. Provider can accept initial values of atoms.

```jsx
const SubTree = () => (
  <Provider>
    <Child />
  </Provider>
)
```


Primitives


Async support is first class in jotai. It fully leverages React Suspense.

> Technically, Suspense usage other than React.lazy is still unsupported / undocumented in React 17. If this is blocking, check out [guides/no-suspense](/jotai/guides/no-suspense).

## Suspense

To use async atoms, you need to wrap your component tree with `<Suspense>`.
If you have `<Provider>` at least one `<Suspense>` is placed inside the `<Provider>`.

```jsx
const App = () => (
  <Provider>
    <Suspense fallback="Loading...">
      <Layout />
    </Suspense>
  </Provider>
)
```

Having more `<Suspense>`s in the component tree is possible.

## Async read atom

The `read` function of an atom can return a promise.
It will suspend and re-render when the promise is fulfilled.

Most importantly, useAtom only returns a resolved value.

```js
const countAtom = atom(1)
const asyncCountAtom = atom(async (get) => get(countAtom) * 2)
// even though the read function returns a promise,

const Component = () => {
  const [num] = useAtom(asyncCountAtom)
  // `num` is guaranteed to be a number.
}
```

An atom becomes async not only if the atom read function is async,
but also one or more of its dependencies are async.

```js
const anotherAtom = atom((get) => get(asyncCountAtom) / 2)
// even though this atom doesn't return a promise,
// it is a read async atom because `asyncCountAtom` is async.
```

## Async write atom

There are another kind of async atoms, called async write atom.
When `write` function of atom returns a promise, it may suspend.
This happens only if the atom is used directly with useAtom,
regardless of its value. (The atom value can be just `null`.)

```js
const countAtom = atom(1)
const asyncIncrementAtom = atom(null, async (get, set) => {
  // await something
  set(countAtom, get(countAtom) + 1)
})

const Component = () => {
  const [, increment] = useAtom(asyncIncrementAtom)
  // it will suspend while `increment` is pending.
}
```

> There's no way to know as of now if an atom suspends because of `read` or `write`.

### Triggering `Suspense` fallback of write atom

This section applies only for "async write atom" not "async read atom", which works different with `Suspense`.

**A write atom will trigger the `Suspense` fallback only if:**

    * the atom's write arg (2nd one) is async
    * the awaited call is made directly and not from inside another containing function

This _will_ trigger the `Suspense` fallback:

```ts
const writeAtom = atom(null, async (get, set) => {
  const response = await new Promise<string>((resolve, _reject) => {
    setTimeout(() => {
      resolve('some returned value')
    }, 2000)
  })
  set(somePrimitiveAtom, 'The returned value is: ' + response)
})
```

This _will not_ trigger the `Suspense` fallback:

```ts
const writeAtom = atom(null, (get, set) => {
  const getResponse = async () => {
    const response = await new Promise<string>((resolve, _reject) => {
      setTimeout(() => {
        resolve('some returned value')
      }, 2000)
    })
    set(somePrimitiveAtom, 'The returned value is: ' + response)
  }
  getResponse()
})
```

But **_both_** of the above will still properly set `somePrimitiveAtom` to the correct values.


This doc describes about the behavior with async.

Async


## How is Jotai different from Zustand?

### Name

Jotai means "state" in Japanese.
Zustand means "state" in German.

### Analogy

Jotai is close to Recoil.
Zustand is close to Redux.

### Where state resides

Jotai state is within React component tree.
Zustand state is in the store outside React.

### How to structure state

Jotai state consists of atoms (i.e. bottom-up).
Zustand state is one object (i.e. top-down).

### Technical difference

The major difference is the state model. Zustand is basically a single store (you could create multiple stores, but they are separated.) Jotai is primitive atoms and composing them. In this sense, it's the matter of programming mental model.

Jotai can be seen as a replacement for useState+useContext. Instead of creating multiple contexts, atoms share one big context.

Zustand is an external store and the hook is to connect the external world to the React world.

### When to use which

- If you need a replacement for useState+useContext, Jotai fits well.
- If you want to update state outside React, Zustand works better.
- If code splitting is important, Jotai should perform well.
- If you prefer Redux devtools, Zustand is good to go.
- If you want to make use of Suspense, Jotai is the one.

---

## How is Jotai different from Recoil?

(Disclaimer: the author is not very familiar with Recoil, this can be biased and not accurate.)

### Developer

- Jotai is developed with collective work by a few developers in Poimandres (formerly react-spring) org.
- Recoil is developed by a team at Facebook.

### Basis

- Jotai is focusing on primitive APIs for lean learning, and it's unopinionated. (The same philosophy with Zustand)
- Recoil is full featured for big apps with various requirements.

### Technical difference

- Jotai depends on atom object referential identities.
- Recoil depends on atom string keys.

### When to use which

- If you want to learn something new, either should work.
- If you like Zustand, Jotai would also be pleasant.
- If your app heavily requires state serialization (storing state in storage, server, or URL), Recoil comes with good features.
- If you need React Context alternatives, Jotai comes with enough features.
- If you would try to create a new library, Jotai might give good primitives.
- Otherwise, both are pretty similar about the general goals and basic techniques, so please try both and give us a feedback.


Comparison


- Text Length example [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://githubbox.com/pmndrs/jotai/tree/master/examples/text_length)

  Count the length and show the uppercase of any text.

- Hacker News example [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://githubbox.com/pmndrs/jotai/tree/master/examples/hacker_news)

  Demonstrate a news articles with Jotai, hit next to see more articles.

- Todos example [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://githubbox.com/pmndrs/jotai/tree/master/examples/todos)

  Record your todo list by typing them into this app, check them if you have completed the task, and switch between `Completed` and `Incompleted` to see the status of your task.

- Todos example with atomFamily and localStorage [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://githubbox.com/pmndrs/jotai/tree/master/examples/todos_with_atomFamily)

  Implement a todo list using atomFamily and localStorage, you can store your todo list to localStorage by click `Save to localStorage`, then remove your todo list and restore them by click `Load from localStorage`.

- Clock with Next.js [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://codesandbox.io/s/nextjs-with-jotai-5ylrj)

  An UTC time eletronic clock implement using Next.js and Jotai.

- Tic Tac Toe game [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://codesandbox.io/s/jotai-tic-tac-6cg3h)

  A game of tic tac toe implemented with Jotai.

- React Three Fiber demo [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://codesandbox.io/s/jotai-r3f-fri9d)

  A simple demo to use Jotai with react-three-fiber


Showcase


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

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

```jsx
const myCamera = useResource()

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

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


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

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

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 automatically handles resizing
- It renders our scene every frame

<Hint>
  Note that the Canvas will be resized to fit the parent div, so you can control how big it is by
  just changing the `width` and `height` of `#canvas-container` in your css.
</Hint>

To actually _render_ something in our scene, we'll add a `mesh` component. In Fiber, every three.js object has an equivalent component:

```js
const myMesh = new THREE.Mesh()
// is equivalent to
<mesh />
```

## Adding a Mesh Component

A [`Mesh`](https://threejs.org/docs/#api/en/objects/Mesh) is a basic object in three.js, and it's used to hold the polygons and the material that are needed to represent the object in 3D space.
We'll create a new mesh using a **BoxGeometry** component for the geometry and a **MeshPhongMaterial** component for the material.

To actually add these objects to our scene, we mount them inside the `<Canvas />` component.

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

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

export default function App() {
  return (
    <div id="canvas-container">
      <Canvas>
        <mesh>
          <boxGeometry />
          <meshPhongMaterial />
        </mesh>
      </Canvas>
    </div>
  )
}
```

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.MeshPhongMaterial()

scene.add(mesh)

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

animate()
```

When you mount a `mesh` component, Fiber is creating a new `THREE.Mesh` object, and the same is done for geometry and material.
Then, geometry and material are _attached_ to their parent.

### Constructor arguments

If we consult the [documentation for THREE's `BoxGeometry`](https://threejs.org/docs/#api/en/geometries/BoxGeometry) we can optionally pass three arguments for: width, length and depth:

```js
const geometry = 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 constructor argument.

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

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

## Adding lights

Next, we will add some lights to our scene, by putting these components as children of `<Canvas />`

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

### Props

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

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 can also receive props.

```jsx
// we are using a THREE.js AmbientLight
<ambientLight
  // we are setting the lights intensity to 0.1
  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 _classes_ that have a `.set()` method (colors, vectors, ect).

```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
  // we are setting the position
  position={[0, 0, 5]}
  // we are setting the color
  color="red"
/>
```

Please refer to the API for [a deeper explanation](/react-three-fiber/API/objects).

## The result

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

export default function App() {
  return (
    <div id="canvas-container">
      <Canvas>
        <ambientLight intensity={0.1} />
        <directionalLight color="red" position={[0, 0, 5]} />
        <mesh>
          <boxGeometry />
          <meshPhongMaterial />
        </mesh>
      </Canvas>
    </div>
  )
}
```

<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)
- 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](/hooks/use-transition) hook or [Transition](/render-props/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


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


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 medias 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 nescessary.
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


## atom

`atom` is a function to create an atom config. The atom config is an immutable object. The atom config itself doesn't hold an atom value. The atom value is stored in a Provider state.

```tsx
// primitive atom
function atom<Value>(initialValue: Value): PrimitiveAtom<Value>

// read-only atom
function atom<Value>(read: (get: Getter) => Value | Promise<Value>): Atom<Value>

// writable derived atom
function atom<Value, Update>(
  read: (get: Getter) => Value | Promise<Value>,
  write: (get: Getter, set: Setter, update: Update) => void | Promise<void>
): WritableAtom<Value, Update>

// write-only derived atom
function atom<Value, Update>(
  read: Value,
  write: (get: Getter, set: Setter, update: Update) => void | Promise<void>
): WritableAtom<Value, Update>
```

- `initialValue`: as the name says, it's an initial value which is the atom's going to return unless its value doesn't get changed.
- `read`: a function that's going to get called on every re-render. The signature of `read` is `(get) => Value | Promise<Value>`, and `get` is a function that takes an atom config and returns its value stored in Provider described below. Dependency is tracked, so if `get` is used for an atom at least once, the `read` will be reevaluated whenever the atom value is changed.
- `write`: a function mostly used for mutating atom's values, for a better description; it gets called whenever we call the second value of the returned pair of `useAtom`, the `useAtom()[1]`. The default value of this function in the primitive atom will change the value of that atom. The signature of `write` is `(get, set, update) => void | Promise<void>`. `get` is similar to the one described above, but it doesn't track the dependency. `set` is a function that takes an atom config and a new value which then updates the atom value in Provider. `update` is an arbitrary value that we receive from the updating function returned by `useAtom` described below.

```tsx
const primitiveAtom = atom(initialValue)
const derivedAtomWithRead = atom(read)
const derivedAtomWithReadWrite = atom(read, write)
const derivedAtomWithWriteOnly = atom(null, write)
```

There are two kinds of atoms: a writable atom and a read-only atom. Primitive atoms are always writable. Derived atoms are writable if the `write` is specified. The `write` of primitive atoms is equivalent to the `setState` of `React.useState`.

### debugLabel

The created atom config can have an optional property `debugLabel`. The debug label will be used to display the atom in debugging. See [Debugging guide](/jotai/guides/debugging) for more information.

Note: Technically, the debug labels don’t have to be unique. However, it’s generally recommended to make them distinguishable.

### onMount

The created atom config can have an optional property `onMount`. `onMount` is a function which takes a function `setAtom` and returns `onUnmount` function optionally.

The `onMount` function will be invoked when the atom is first used in a provider, and `onUnmount` will be invoked when it’s not used. In some edge cases, an atom can be unmounted and then mounted immediately.

```tsx
const anAtom = atom(1)
anAtom.onMount = (setAtom) => {
  console.log('atom is mounted in provider')
  setAtom(c => c + 1) // increment count on mount
  return () => { ... } // return optional onUnmount function
}
```

Invoking `setAtom` function will invoke the atom’s `write`. Customizing `write` allows changing the behavior.

```tsx
const countAtom = atom(1)
const derivedAtom = atom(
  (get) => get(countAtom),
  (get, set, action) => {
    if (action.type === 'init') {
      set(countAtom, 10)
    } else if (action.type === 'inc') {
      set(countAtom, (c) => c + 1)
    }
  }
)
derivedAtom.onMount = (setAtom) => {
  setAtom({ type: 'init' })
}
```

## Provider

```ts
const Provider: React.FC<{
  initialValues?: Iterable<readonly [AnyAtom, unknown]>
  scope?: Scope
}>
```

Atom configs don't hold values. Atom values reside in separate stores. A Provider is a component that contains a store and provides atom values under the component tree. A Provider works just like React context provider. If you don't use a Provider, it works as provider-less mode with a default store. A Provider will be necessary if we need to hold different atom values for different component trees. Provider also has some capabilities described below, which doesn't exist in the provider-less mode.

```jsx
const Root = () => (
  <Provider>
    <App />
  </Provider>
)
```

### `initialValues` prop

A Provider accepts an optional prop `initialValues` which you can specify
some initial atom values.
The use cases of this are testing and server side rendering.

#### Example

```jsx
const TestRoot = () => (
  <Provider initialValues=[[atom1, 1], [atom2, 'b']]>
    <Component />
  </Provider>
)
```

#### TypeScript

The `initialValues` prop is not type friendly.
We can mitigate it by using a helper function.

```ts
const createInitialValues = () => {
  const initialValues: (readonly [Atom<unknown>, unknown])[] = []
  const get = () => initialValues
  const set = <Value>(anAtom: Atom<Value>, value: Value) => {
    initialValues.push([anAtom, value])
  }
  return { get, set }
}
```

### `scope` prop

A Provider accepts an optional prop `scope` which you can use for scoped atoms.
It works only for atoms with the same scope.
The recommendation for the scope value is a unique symbol.
The use case of scope is for library usage.

#### Example

```jsx
const myScope = Symbol()

const anAtom = atom('')
anAtom.scope = myScope

const LibraryRoot = () => (
  <Provider scope={myScope}>
    <Component />
  </Provider>
)
```

## useAtom

```ts
// primitive or writable derived atom
function useAtom<Value, Update>(atom: WritableAtom<Value, Update>): [Value, SetAtom<Update>]

// read-only atom
function useAtom<Value>(atom: Atom<Value>): [Value, never]
```

The useAtom hook is to read an atom value stored in the Provider. It returns the atom value and an updating function as a tuple, just like useState. It takes an atom config created with `atom()`. Initially, there is no value stored in the Provider. The first time the atom is used via `useAtom`, it will add an initial value in the Provider. If the atom is a derived atom, the read function is executed to compute an initial value. When an atom is no longer used, meaning all the components using it is unmounted, and the atom config no longer exists, the value is removed from the Provider.

```js
const [value, updateValue] = useAtom(anAtom)
```

The `updateValue` takes just one argument, which will be passed to the third argument of writeFunction of the atom. The behavior totally depends on how the writeFunction is implemented.

---

## Notes

### How atom dependency works

To begin with, let's explain this. In the current implementation, every time we invoke the "read" function, we refresh the dependencies and dependents. For example, If A depends on B, it means that B has a dependency on A, and A is a dependent of B.

```js
const uppercaseAtom = atom((get) => get(textAtom).toUpperCase())
```

The read function is the first parameter of the atom.
The dependency will initially be empty. On first use, we run the read function and know that `uppercaseAtom` depends on `textAtom`. `textAtom` has a dependency on `uppercaseAtom`. So, add `uppercaseAtom` to the dependents of `textAtom`.
When we re-run the read function (because its dependency (=textAtom) is updated),
the dependency is built again, which is the same in this case. We then remove stale dependents and replace with the latest one.

### Atoms can be created on demand

Basic examples in readme only show defining atoms globally outside components.
There is no restrictions about when we create an atom.
As long as we know atoms are identified by their object referential identity,
it's okay to create them at anytime.

If you create atoms in render functions, you would typically want to use
a hook like `useRef` or `useMemo` for memoization. If not, the atom would be created everytime the component renders.

You can create an atom and store it wth `useState` or even in another atom.
See an example in [issue #5](https://github.com/pmndrs/jotai/issues/5).

You can cache atoms somewhere globally.
See [this example](https://twitter.com/dai_shi/status/1317653548314718208) or
[that example](https://github.com/pmndrs/jotai/issues/119#issuecomment-706046321).

Check [`atomFamily`](/jotai/api/utils#atom-family) in utils for parameterized atoms.

### Some more notes about atoms

- If you create a primitive atom, it will use predefined read/write functions to emulate `useState` behavior.
- If you create an atom with read/write functions, they can provide any behavior with some restrictions as follows.
- `read` function will be invoked during React render phase, so the function has to be pure. What is pure in React is described [here](https://gist.github.com/sebmarkbage/75f0838967cd003cd7f9ab938eb1958f).
- `write` function will be invoked where you called initially and in useEffect for following invocations. So, you shouldn't call `write` in render.
- When an atom is initially used with `useAtom`, it will invoke `read` function to get the initial value, this is recursive process. If an atom value exists in Provider, it will be used instead of invoking `read` function.
- Once an atom is used (and stored in Provider), it's value is only updated if its dependencies are updated (including updating directly with useAtom).


Core


## atomWithStorage

Ref: https://github.com/pmndrs/jotai/pull/394

```ts
import { useAtom } from 'jotai'
import { atomWithStorage } from 'jotai/utils'

const darkModeAtom = atomWithStorage('darkMode', false)

const Page = () => {
  const [darkMode, setDarkMode] = useAtom(darkModeAtom)

  return (
    <>
      <h1>Welcome to {darkMode ? 'dark' : 'light'} mode!</h1>
      <button onClick={() => setDarkMode(!darkMode)}>toggle theme</button>
    </>
  )
}
```

The `atomWithStorage` function creates an atom with a value persisted in `localStorage` or `sessionStorage` for React or `AsyncStorage` for React Native.

### Parameters

**key** (required): a unique string used as the key when syncing state with localStorage, sessionStorage, or AsyncStorage

**initialValue** (required): the initial value of the atom

**storage** (optional): an object with `getItem` and `setItem` methods for storing/retreiving persisted state; defaults to using `localStorage` for storage/retreival and `JSON.stringify()`/`JSON.parse()` for serialization/deserialization

<Codesandbox id="7dfib" />

### Server-side rendering

Any JSX markup that depends on the value of a stored atom (e.g., a `className` or `style` prop) will use the `initialValue` when rendered on the server (since `localStorage` and `sessionStorage` are not available on the server).

This means that there will be a mismatch between what is originally served to the user's browser as HTML and what is expected by React during the rehydration process if the user has a `storedValue` that differs from the `initialValue`.

The suggested workaround for this issue is to only render the content dependent on the `storedValue` client-side by wrapping it in a [custom `<ClientOnly>` wrapper](https://www.joshwcomeau.com/react/the-perils-of-rehydration/#abstractions), which only renders after rehydration. Alternative solutions are technically possible, but would require a brief "flicker" as the `initialValue` is swapped to the `storedValue`, which can result in an unpleasant user experience, so this solution is advised.

## useUpdateAtom

Ref: https://github.com/pmndrs/jotai/issues/26

```jsx
import { atom, useAtom } from 'jotai'
import { useUpdateAtom } from 'jotai/utils'

const countAtom = atom(0)

const Counter = () => {
  const [count] = useAtom(countAtom)
  return <div>count: {count}</div>
}

const Controls = () => {
  const setCount = useUpdateAtom(countAtom)
  const inc = () => setCount((c) => c + 1)
  return <button onClick={inc}>+1</button>
}
```

<Codesandbox id="3q11k" />

## useAtomValue

Ref: https://github.com/pmndrs/jotai/issues/212

```jsx
import { atom, Provider, useAtom } from 'jotai'
import { useAtomValue } from 'jotai/utils'

const countAtom = atom(0)

const Counter = () => {
  const setCount = useUpdateAtom(countAtom)
  const count = useAtomValue(countAtom)
  return (
    <>
      <div>count: {count}</div>
      <button onClick={() => setCount(count + 1)}>+1</button>
    </>
  )
}
```

<Codesandbox id="1x90m" />

## atomWithReset

Ref: https://github.com/pmndrs/jotai/issues/41

```ts
function atomWithReset<Value>(
  initialValue: Value
): WritableAtom<Value, SetStateAction<Value> | typeof RESET>
```

Creates an atom that could be reset to its `initialValue` with
[`useResetAtom`](/jotai/api/utils#use-reset-atom) hook. It works exactly the same
way as primitive atom would, but you are also able to set it to a special value
[`RESET`](/jotai/api/utils#reset). See examples in [Resettable atoms](/jotai/guides/resettable).

### Example

```js
import { atomWithReset } from 'jotai/utils'

const dollarsAtom = atomWithReset(0)
const todoListAtom = atomWithReset([{ description: 'Add a todo', checked: false }])
```

## useResetAtom

```ts
function useResetAtom<Value>(anAtom: WritableAtom<Value, typeof RESET>): () => void | Promise<void>
```

Resets a [Resettable atom](/jotai/guides/resettable) to its initial value.

### Example

```jsx
import { useResetAtom } from 'jotai/utils'
import { todoListAtom } from './store'

const TodoResetButton = () => {
  const resetTodoList = useResetAtom(todoListAtom)
  return <button onClick={resetTodoList}>Reset</button>
}
```

## RESET

Ref: https://github.com/pmndrs/jotai/issues/217

```ts
const RESET: unique symbol
```

Special value that is accepted by [Resettable atoms](/jotai/guides/resettable)
created with [`atomWithReset`](/jotai/api/utils#atom-with-reset), [`atomWithDefault`](/jotai/api/utils#atom-with-default)
or writable atom created with `atom` if it accepts `RESET` symbol.

### Example

```jsx
import { atom } from 'jotai'
import { atomWithReset, useResetAtom, RESET } from 'jotai/utils'

const dollarsAtom = atomWithReset(0)
const centsAtom = atom(
  (get) => get(dollarsAtom) * 100,
  (get, set, newValue: number | typeof RESET) =>
    set(dollarsAtom, newValue === RESET ? newValue : newValue / 100)
)

const ResetExample: React.FC = () => {
  const setDollars = useUpdateAtom(dollarsAtom)
  const resetCents = useResetAtom(centsAtom)

  return (
    <>
      <button onClick={() => setDollars(RESET)}>Reset dollars</button>
      <button onClick={resetCents}>Reset cents</button>
    </>
  )
}
```

## useReducerAtom

```jsx
import { atom } from 'jotai'
import { useReducerAtom } from 'jotai/utils'

const countReducer = (prev, action) => {
  if (action.type === 'inc') return prev + 1
  if (action.type === 'dec') return prev - 1
  throw new Error('unknown action type')
}

const countAtom = atom(0)

const Counter = () => {
  const [count, dispatch] = useReducerAtom(countAtom, countReducer)
  return (
    <div>
      {count}
      <button onClick={() => dispatch({ type: 'inc' })}>+1</button>
      <button onClick={() => dispatch({ type: 'dec' })}>-1</button>
    </div>
  )
}
```

<Codesandbox id="eg0mw" />

## atomWithReducer

Ref: https://github.com/pmndrs/jotai/issues/38

```js
import { atomWithReducer } from 'jotai/utils'

const countReducer = (prev, action) => {
  if (action.type === 'inc') return prev + 1
  if (action.type === 'dec') return prev - 1
  throw new Error('unknown action type')
}

const countReducerAtom = atomWithReducer(0, countReducer)
```

<Codesandbox id="g3tsx" />

## atomWithDefault

Ref: https://github.com/pmndrs/jotai/issues/352

### Usage

This is a function to create a resettable primitive atom.
Its default value can be specified with a read function instead of a static initial value.

```js
import { atomWithDefault } from 'jotai/utils'

const count1Atom = atom(1)
const count2Atom = atomWithDefault((get) => get(count1Atom) * 2)
```

### Codesandbox

<Codesandbox id="unfro" />

### Resetting default values

You can reset the value of an `atomWithDefault` atom to its original default value.

```js
import { useAtom } from 'jotai'
import { atomWithDefault, useResetAtom, RESET } from 'jotai/utils'

const count1Atom = atom(1)
const count2Atom = atomWithDefault((get) => get(count1Atom) * 2)

const Counter: React.FC = () => {
  const [count1, setCount1] = useAtom(count1Atom)
  const [count2, setCount2] = useAtom(count2Atom)
  const resetCount2 = useResetAtom(count2Atom)

  return (
    <>
      <div>count1: {count1}, count2: {count2}</div>
      <button onClick={() => setCount1((c) => c + 1)}>increment count1</button>
      <button onClick={() => setCount2((c) => c + 1)}>increment count2</button>
      <button onClick={() => resetCount2()}>Reset with useResetAtom</button>
      <button onClick={() => setCount2(RESET)}>Reset with RESET const</button>
    </>
  )
}
```

This can be useful when an `atomWithDefault` atom value is overwritten
using the `set` function, in which case the provided `getter` function
is no longer used and any change in dependencies atoms will not trigger an update.

Resetting the value allows us to restore its original default value,
discarding changes made previously via the `set` function.

## atomWithHash

### Usage

```js
atomWithHash(key, initialValue): PrimitiveAtom
```

This creats a new atom that is connected with URL hash.
The hash must be in the URLSearchParams format.
It's two-way binding: changing atom value will change the hash and
changing the hash will change the atom value.
This function works only with DOM.

### Examples

```jsx
import { useAtom } from 'jotai'
import { atomWithHash } from 'jotai/utils'
const countAtom = atomWithHash('count', 1)
const Counter: React.FC = () => {
  const [count, setCount] = useAtom(countAtom)
  return (
    <>
      <div>count: {count}</div>
      <button onClick={() => setCount((c) => c + 1)}>button</button>
    </>
  )
}
```

### Codesandbox

<Codesandbox id="d5kn6" />

## atomFamily

Ref: https://github.com/pmndrs/jotai/issues/23

### Usage

```js
atomFamily(initializeAtom, areEqual): (param) => Atom
```

This will create a function that takes `param` and returns an atom.
If it's already created, it will return it from the cache.
`initializeAtom` is function that can return any kind of atom (`atom()`, `atomWithDefault()`, ...).
Note that `areEqual` is optional, which tell
if two params are equal (defaults to `Object.is`).

To reproduce the similar behavior to [Recoil's atomFamily/selectorFamily](https://recoiljs.org/docs/api-reference/utils/atomFamily),
specify a deepEqual function to `areEqual`. For example:

```js
import { atom } from 'jotai'
import deepEqual from 'fast-deep-equal'

const fooFamily = atomFamily((param) => atom(param), deepEqual)
```

### TypeScript

The atom family types will be inferred from initializeAtom. Here's a typical usage with a primitive atom.

```ts
import type { PrimitiveAtom } from 'jotai'

/**
 * here the atom(id) returns a PrimitiveAtom<number>
 * and PrimitiveAtom<number> is a WritableAtom<number, SetStateAction<number>>
 */
const myFamily = atomFamily((id: number) => atom(id)).
```

You can explicitly declare the type of parameter, value, and atom's setState function using TypeScript generics.

```ts
atomFamily<Param, Value, Update>(initializeAtom: (param: Param) => WritableAtom<Value, Update>, areEqual?: (a: Param, b: Param) => boolean)
atomFamily<Param, Value>(initializeAtom: (param: Param) => Atom<Value>, areEqual?: (a: Param, b: Param) => boolean)
```

If you want to explicitly declare the atomFamily for a primitive atom, you need to use `SetStateAction`.

```ts
type SetStateAction<Value> = Value | ((prev: Value) => Value)

const myFamily = atomFamily<number, number, SetStateAction<number>>((id: number) => atom(id))
```

### Examples

```js
import { atom } from 'jotai'
import { atomFamily } from 'jotai/utils'

const todoFamily = atomFamily((name) => atom(name))

todoFamily('foo')
// this will create a new atom('foo'), or return the one if already created
```

```js
import { atom } from 'jotai'
import { atomFamily } from 'jotai/utils'

const todoFamily = atomFamily((name) =>
  atom(
    (get) => get(todosAtom)[name],
    (get, set, arg) => {
      const prev = get(todosAtom)
      return { ...prev, [name]: { ...prev[name], ...arg } }
    }
  )
)
```

```js
import { atom } from 'jotai'
import { atomFamily } from 'jotai/utils'

const todoFamily = atomFamily(
  ({ id, name }) => atom({ name }),
  (a, b) => a.id === b.id
)
```

### Codesandbox

<Codesandbox id="8zfrn" />

## selectAtom

Ref: https://github.com/pmndrs/jotai/issues/36

```js
function selectAtom<Value, Slice>(
  anAtom: Atom<Value>,
  selector: (v: Value) => Slice,
  equalityFn: (a: Slice, b: Slice) => boolean = Object.is
): Atom<Slice>
```

This function creates a derived atom whose value is a function of the original atom's value,
determined by `selector.`
The selector function runs whenever the original atom changes; it updates the derived atom
only if `equalityFn` reports that the derived value has changed.
By default, `equalityFn` is reference equality, but you can supply your favorite deep-equals
function to stabilize the derived value where necessary.

### Examples

```js
const defaultPerson = {
  name: {
    first: 'Jane',
    last: 'Doe',
  },
  birth: {
    year: 2000,
    month: 'Jan',
    day: 1,
    time: {
      hour: 1,
      minute: 1,
    },
  },
}

// Original atom.
const personAtom = atom(defaultPerson)

// Tracks person.name. Updated when person.name object changes, even
// if neither name.first nor name.last actually change.
const nameAtom = selectAtom(personAtom, (person) => person.name)

// Tracks person.birth. Updated when year, month, day, hour, or minute changes.
// Use of deepEquals means that this atom doesn't update if birth field is
// replaced with a new object containing the same data. E.g., if person is re-read
// from a database.
const birthAtom = selectAtom(personAtom, (person) => person.birth, deepEquals)
```

Ref: https://codesandbox.io/s/react-typescript-forked-8czek

## useAtomCallback

Ref: https://github.com/pmndrs/jotai/issues/60

### Usage

```js
useAtomCallback(
  callback: (get: Getter, set: Setter, arg: Arg) => Result
): (arg: Arg) => Promise<Result>
```

This hook allows to interact with atoms imperatively.
It takes a callback function that works like atom write function,
and returns a function that returns a promise.

The callback to pass in the hook must be stable (should be wrapped with useCallback).

### Examples

```jsx
import { useEffect, useState, useCallback } from 'react'
import { Provider, atom, useAtom } from 'jotai'
import { useAtomCallback } from 'jotai/utils'

const countAtom = atom(0)

const Counter = () => {
  const [count, setCount] = useAtom(countAtom)
  return (
    <>
      {count} <button onClick={() => setCount((c) => c + 1)}>+1</button>
    </>
  )
}

const Monitor = () => {
  const [count, setCount] = useState(0)
  const readCount = useAtomCallback(
    useCallback((get) => {
      const currCount = get(countAtom)
      setCount(currCount)
      return currCount
    }, [])
  )
  useEffect(() => {
    const timer = setInterval(async () => {
      console.log(await readCount())
    }, 1000)
    return () => {
      clearInterval(timer)
    }
  }, [readCount])
  return <div>current count: {count}</div>
}
```

### Codesandbox

<Codesandbox id="6ur43" />

## freezeAtom

```js
import { atom } from 'jotai'
import { freezeAtom } from 'jotai/utils'

const objAtom = freezeAtom(atom({ count: 0 }))
```

`freezeAtom` takes an existing atom and returns a new derived atom.
The returned atom is "frozen" which means when you use the atom
with `useAtom` in components or `get` in other atoms,
the atom value will be deeply frozen with Object.freeze.
It would be useful to find bugs where you accidentally tried
to mutate objects which can lead to unexpected behavior.

## freezeAtomCreator

```js
import { atom } from 'jotai'
import { freezeAtomCreator } from 'jotai/utils'

const createFrozenAtom = freezeAtomCreator(atom)
const objAtom = createFrozenAtom({ count: 0 })
```

Instead of create a frozen atom from an existing atom,
`freezeAtomCreator` takes an atom creator function and returns a new function.
You can use this not only for `atom`, but also for other `atomWith*` creators such as `atomWithReduer`.

## splitAtom

The `splitAtom` utility is useful for when you want to get an atom for each element in a list.
It works for read/write atoms that contain a list. When used on such an atom, it returns an atom
which itself contains a list of atoms, each corresponding to the respective item in the original list.

A simplified type signature would be:

```ts
type SplitAtom = <Item>(arrayAtom: PrimitiveAtom<Array<Item>>): Atom<Array<PrimitiveAtom<Item>>>
```

Additionally, the atom returned by `splitAtom` contains a removal function in the `write` direction,
this is useful for when you want a simple way to remove each element in the original atom.

See the below example for usage.

### codesandbox

<Codesandbox id="7nir9" />

```tsx
import * as React from 'react'
import { Provider, atom, useAtom, PrimitiveAtom } from 'jotai'
import { splitAtom } from 'jotai/utils'
import './styles.css'

const initialState = [
  {
    task: 'help the town',
    done: false,
  },
  {
    task: 'feed the dragon',
    done: false,
  },
]

const todosAtom = atom(initialState)
const todoAtomsAtom = splitAtom(todosAtom)

const TodoList = () => {
  const [todoAtoms, removeTodoAtom] = useAtom(todoAtomsAtom)
  return (
    <ul>
      {todoAtoms.map((todoAtom) => (
        <TodoItem todoAtom={todoAtom} remove={() => removeTodoAtom(todoAtom)} />
      ))}
    </ul>
  )
}

type TodoType = typeof initialState[number]

const TodoItem = ({
  todoAtom,
  remove,
}: {
  todoAtom: PrimitiveAtom<TodoType>
  remove: () => void
}) => {
  const [todo, setTodo] = useAtom(todoAtom)
  return (
    <div>
      <input
        value={todo.task}
        onChange={(e) => {
          setTodo((oldValue) => ({ ...oldValue, task: e.target.value }))
        }}
      />
      <input
        type="checkbox"
        checked={todo.done}
        onChange={() => {
          setTodo((oldValue) => ({ ...oldValue, done: !oldValue.done }))
        }}
      />
      <button onClick={remove}>remove</button>
    </div>
  )
}

const App = () => (
  <Provider>
    <TodoList />
  </Provider>
)

export default App
```

## waitForAll

Sometimes you have multiple async atoms in your components:

```tsx
const dogsAtom = atom(async (get) => {
  const response = await fetch('/dogs')
  return await response.json()
})
const catsAtom = atom(async (get) => {
  const response = await fetch('/cats')
  return await response.json()
})

const App = () => {
  const [dogs] = useAtom(dogsAtom)
  const [cats] = useAtom(catsAtom)
  // ...
}
```

However, this will start fetching one at the time, which is not optimal - It would be better if we can start fetching both as soon as possible.

The `waitForAll` utility is a concurrency helper, which allows us to evaluate multiple async atoms:

```tsx
const dogsAtom = atom(async (get) => {
  const response = await fetch('/dogs')
  return await response.json()
})
const catsAtom = atom(async (get) => {
  const response = await fetch('/cats')
  return await response.json()
})

const App = () => {
  const [[dogs, cats]] = useAtom(waitForAll([dogsAtom, catsAtom]))
  // or ...
  const [dogs, cats] = useAtomValue(waitForAll([dogsAtom, catsAtom]))
  // ...
}
```

You can also use `waitForAll` inside an atom - It's also possible to name them for readability:

```tsx
const dogsAtom = atom(async (get) => {
  const response = await fetch('/dogs')
  return await response.json()
})
const catsAtom = atom(async (get) => {
  const response = await fetch('/cats')
  return await response.json()
})

const animalsAtom = atom((get) => {
  return get(
    waitForAll({
      dogs: dogsAtom,
      cats: catsAtom,
    })
  )
})

const App = () => {
  const [{ dogs, cats }] = useAtom(animalsAtom)
  // or ...
  const { dogs, cats } = useAtomValue(animalsAtom)
  // ...
}
```

### Codesandbox

<Codesandbox id="krwsv" />


Utils


## useAtomDevtools

`useAtomDevtools` is a React hook that manages ReduxDevTools integration for a particular atom.

```ts
function useAtomDevtools<Value>(anAtom: WritableAtom<Value, Value>, name?: string): void
```

The `useAtomDevtools` hook accepts a generic type parameter (mirroring the type stored in the atom). Additionally, the hook accepts two invocation parameters, `anAtom` and `name`.
`anAtom` is the atom that will be attached to the devtools instance. `name` is an optional parameter that defines the debug label for the devtools instance. If `name` is undefined, `atom.debugLabel` will be used instead.

### Example

```typescript
import { useAtomDevtools } from 'jotai/devtools'

// The interface for the type stored in the atom.
export interface Task {
  label: string
  complete: boolean
}

// The atom to debug.
export const tasksAtom = atom<Task[]>([])

// If the useAtomDevtools name parameter is undefined, this value will be used instead.
tasksAtom.debugLabel = 'Tasks'

export const useTasksDevtools = () => {
  // The hook can be called simply by passing an atom for debugging.
  useAtomDevtools(tasksAtom)

  // Specify a custom type parameter
  useAtomDevtools<Task[]>(tasksAtom)

  // You can attach two devtools instances to the same atom and differentiate them with custom names.
  useAtomDevtools(tasksAtom, 'Tasks (Instance 1)')
  useAtomDevtools(tasksAtom, 'Tasks (Instance 2)')
}
```

## useAtomsSnapshot

⚠️ Note: This hook only works in a `process.env.NODE_ENV !== 'production'` environment.

`useAtomsSnapshot` takes a snapshot of the currently mounted atoms and their state.

```ts
function useAtomsSnapshot(scope?: Scope): AtomsSnapshot
```

It accepts an atom `scope` parameter and will return an `AtomsSnapshot`, which is basically a `Map<AnyAtom, unknown>`. You can use the `Map` API to iterate over atoms and their state.
This hook is primarily meant for debugging and devtools use cases.

Be careful using this hook because it will cause the component to re-render for all state changes.

### Example

```ts
import { Provider } from 'jotai'
import { useAtomsSnapshot } from 'jotai/devtools'

const RegisteredAtoms = () => {
  const atoms = useAtomsSnapshot()

  return (
    <div>
      <p>Atom count: {atoms.size}</p>
      <div>
        {Array.from(atoms).map(([atom, atomValue]) => (
          <p key={`${atom}`}>{`${atom.debugLabel}: ${atomValue}`}</p>
        ))}
      </div>
    </div>
  )
}

const App = () => (
  <Provider>
    <RegisteredAtoms />
  </Provider>
)
```

## useGotoAtomsSnapshot

⚠️ Note: This hook only works in a `process.env.NODE_ENV !== 'production'` environment.

`useGotoAtomsSnapshot` will update the current Jotai state to match the passed snapshot.

```ts
function useGotoAtomsSnapshot(
  scope?: Scope
): (values: Iterable<readonly [AnyAtom, unknown]>) => void
```

This hook returns a callback, which takes a `snapshot` from the `useAtomsSnapshot` hook and will update the Jotai state. It accepts an atom `scope` parameter and will error if the atoms have mixed scopes.
This hook is primarily meant for debugging and devtools use cases.

### Example

```ts
import { Provider } from 'jotai'
import { useAtomsSnapshot, useGotoAtomsSnapshot } from 'jotai/devtools'

const petAtom = atom('cat')
const colorAtom = atom('blue')

const UpdateSnapshot: React.FC = () => {
  const snapshot = useAtomsSnapshot()
  const goToSnapshot = useGotoAtomsSnapshot()
  return (
    <button
      onClick={() => {
        const newSnapshot = new Map(snapshot)
        newSnapshot.set(petAtom, 'dog')
        newSnapshot.set(colorAtom, 'green')
        goToSnapshot(newSnapshot)
      }}
    >
      Go to snapshot
    </button>
  )
}
```


This doc describes `jotai/devtool` bundle.

Devtools


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!

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


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


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


## Version requirement

Jotai uses TypeScript 3.8+ syntax. Upgrade your TypeScript version if you're on 3.7.5 or lower.

## Notes

### Primitive atoms are basically type inferred

```ts
const numAtom = atom(0) // primitive number atom
const strAtom = atom('') // primitive string atom
```

### Primitive atoms can be explicitly typed

```ts
const numAtom = atom<number>(0)
const numAtom = atom<number | null>(0)
const arrAtom = atom<string[]>([])
```

### Derived atoms are also type inferred and explicitly typed

```ts
const asyncStrAtom = atom(async () => "foo")
const writeOnlyAtom = atom(null, (_get, set, str: string) => set(fooAtom, str)
const readWriteAtom = atom<string, number>(
  get => get(strAtom),
  (_get, set, num) => set(strAtom, String(num))
)
```

### useAtom is typed based on atom types

```ts
const [num, setNum] = useAtom(primitiveNumAtom)
const [num] = useAtom(readOnlyNumAtom)
const [, setNum] = useAtom(writeOnlyNumAtom)
```


TypeScript


## Using React Dev Tools

You can use [React Dev Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi)
to inspect Jotai state. To achieve that [useDebugValue](https://reactjs.org/docs/hooks-reference.html#usedebugvalue)
is used inside custom hooks. Keep in mind that it only works in dev mode
(`NODE_ENV === 'development'`).

### Provider

If you select Jotai `Provider` component in the React Dev Tools to see custom
hook "DebugState" which allows you to see all atom states,
which is a map of atom config and atom values & dependents.

By default each state has the label like `1:<no debugLabel>` with number being
internal `key` assigned to each atom automatically. But you can add labels to
atoms to help you distinguish them more easily with `debugLabel`.

```js
const countAtom = atom(0)
if (process.env.NODE_ENV !== 'production') {
  countAtom.debugLabel = 'count'
}
```

So it will show up as `1:count` instead.

### useAtom

`useAtom` calls `useDebugValue` for atom values, so if you select the component
in React Dev Tools you would see "Atom" hooks for each atom that is used in the
component along with the value it has right now.

## Using Redux DevTools

You can use [Redux DevTools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd)
to inspect the state of a particular atom. Please refer to [`useAtomDevtools`](/jotai/api/devtools#use-atom-devtools) hook from `jotai/devtools` bundle.

## Frozen Atoms

To find bugs where you accidentally tried to mutate objects stored in atoms you
could use [`freezeAtom`](/jotai/api/utils#freeze-atom) or
[`atomFrozenInDev`](/jotai/api/utils#atom-frozen-in-dev) from `jotai/utils` bundle.
Which returns atoms value that is deeply freezed with `Object.freeze`.


Debugging


Jotai has an [atomWithStorage function in the utils bundle](/jotai/api/utils#atom-with-storage) for persistance that supports persisting state in `sessionStorage`, `localStorage`, `AsyncStorage`, or the URL hash.

There are also several alternate implementations here:

## A simple pattern with localStorage

```js
const strAtom = atom(localStorage.getItem('myKey') ?? 'foo')

const strAtomWithPersistence = atom(
  (get) => get(strAtom),
  (get, set, newStr) => {
    set(strAtom, newStr)
    localStorage.setItem('myKey', newStr)
  }
)
```

## A helper function with localStorage and JSON parse

```js
const atomWithLocalStorage = (key, initialValue) => {
  const getInitialValue = () => {
    const item = localStorage.getItem(key)
    if (item !== null) {
      return JSON.parse(item)
    }
    return initialValue
  }
  const baseAtom = atom(getInitialValue())
  const derivedAtom = atom(
    (get) => get(baseAtom),
    (get, set, update) => {
      const nextValue = typeof update === 'function' ? update(get(baseAtom)) : update
      set(baseAtom, nextValue)
      localStorage.setItem(key, JSON.stringify(nextValue))
    }
  )
  return derivedAtom
}
```

(Error handling should be added.)

## A helper function with AsyncStorage and JSON parse

This requires [onMount](/jotai/api/core#on-mount).

```js
const atomWithAsyncStorage = (key, initialValue) => {
  const baseAtom = atom(initialValue)
  baseAtom.onMount = (setValue) => {
    ;(async () => {
      const item = await AsyncStorage.getItem(key)
      setValue(JSON.parse(item))
    })()
  }
  const derivedAtom = atom(
    (get) => get(baseAtom),
    (get, set, update) => {
      const nextValue = typeof update === 'function' ? update(get(baseAtom)) : update
      set(baseAtom, nextValue)
      AsyncStorage.setItem(key, JSON.stringify(nextValue))
    }
  )
  return derivedAtom
}
```

---

## A serialize atom pattern

```tsx
const serializeAtom = atom<
  null,
  { type: 'serialize'; callback: (value: string) => void } | { type: 'deserialize'; value: string }
>(null, (get, set, action) => {
  if (action.type === 'serialize') {
    const obj = {
      todos: get(todosAtom).map(get),
    }
    action.callback(JSON.stringify(obj))
  } else if (action.type === 'deserialize') {
    const obj = JSON.parse(action.value)
    // needs error handling and type checking
    set(
      todosAtom,
      obj.todos.map((todo: Todo) => atom(todo))
    )
  }
})

const Persist: React.FC = () => {
  const [, dispatch] = useAtom(serializeAtom)
  const save = () => {
    dispatch({
      type: 'serialize',
      callback: (value) => {
        localStorage.setItem('serializedTodos', value)
      },
    })
  }
  const load = () => {
    const value = localStorage.getItem('serializedTodos')
    if (value) {
      dispatch({ type: 'deserialize', value })
    }
  }
  return (
    <div>
      <button onClick={save}>Save to localStorage</button>
      <button onClick={load}>Load from localStorage</button>
    </div>
  )
}
```

### Examples

<Codesandbox id="ijyxm" />

## A pattern with atomFamily

```tsx
const serializeAtom = atom<
  null,
  { type: 'serialize'; callback: (value: string) => void } | { type: 'deserialize'; value: string }
>(null, (get, set, action) => {
  if (action.type === 'serialize') {
    const todos = get(todosAtom)
    const todoMap: Record<string, { title: string; completed: boolean }> = {}
    todos.forEach((id) => {
      todoMap[id] = get(todoAtomFamily({ id }))
    })
    const obj = {
      todos,
      todoMap,
      filter: get(filterAtom),
    }
    action.callback(JSON.stringify(obj))
  } else if (action.type === 'deserialize') {
    const obj = JSON.parse(action.value)
    // needs error handling and type checking
    set(filterAtom, obj.filter)
    obj.todos.forEach((id: string) => {
      const todo = obj.todoMap[id]
      set(todoAtomFamily({ id, ...todo }), todo)
    })
    set(todosAtom, obj.todos)
  }
})

const Persist: React.FC = () => {
  const [, dispatch] = useAtom(serializeAtom)
  const save = () => {
    dispatch({
      type: 'serialize',
      callback: (value) => {
        localStorage.setItem('serializedTodos', value)
      },
    })
  }
  const load = () => {
    const value = localStorage.getItem('serializedTodos')
    if (value) {
      dispatch({ type: 'deserialize', value })
    }
  }
  return (
    <div>
      <button onClick={save}>Save to localStorage</button>
      <button onClick={load}>Load from localStorage</button>
    </div>
  )
}
```

### Examples

<Codesandbox id="eilkg" />


Persistence


## You can't return promises in server side rendering

```js
const postData = atom((get) => {
  const id = get(postId)
  if (isSSR || prefetchedPostData[id]) {
    return prefetchedPostData[id] || EMPTY_POST_DATA
  }
  return fetchData(id) // returns a promise
})
```

## Hydration is possible with care

Check the following examples.

## Examples

### Clock

<Codesandbox id="5ylrj" />

### HN Posts

<Codesandbox id="pm0l8" />


Next.js


The Jotai core doesn't support resettable atoms.
But you can create those with helper functions from `jotai/utils`.

## Primitive resettable atom with atomWithReset / useResetAtom

```jsx
import { useAtom } from 'jotai'
import { atomWithReset, useResetAtom } from 'jotai/utils'

const todoListAtom = atomWithReset([{ description: 'Add a todo', checked: false }])

const TodoList = () => {
  const [todoList, setTodoList] = useAtom(todoListAtom)
  const resetTodoList = useResetAtom(todoListAtom)

  return (
    <>
      <ul>
        {todoList.map((todo) => (
          <li>{todo.description}</li>
        ))}
      </ul>

      <button
        onClick={() =>
          setTodoList((l) => [
            ...l,
            {
              description: `New todo ${new Date().toDateString()}`,
              checked: false,
            },
          ])
        }
      >
        Add todo
      </button>
      <button onClick={resetTodoList}>Reset</button>
    </>
  )
}
```

### Examples

<Codesandbox id="w91cq" />

## Derived atom with RESET symbol

```jsx
import { atom, useAtom } from 'jotai'
import { atomWithReset, useResetAtom, RESET } from 'jotai/utils'

const dollarsAtom = atomWithReset(0)
const centsAtom = atom(
  (get) => get(dollarsAtom) * 100,
  (get, set, newValue: number | typeof RESET) =>
    set(dollarsAtom, newValue === RESET ? newValue : newValue / 100)
)

const ResetExample: React.FC = () => {
  const [dollars] = useAtom(dollarsAtom)
  const setCents = useUpdateAtom(centsAtom)
  const resetCents = useResetAtom(centsAtom)

  return (
    <>
      <h3>Current balance ${dollars}</h3>
      <button onClick={() => setCents(100)}>Set $1</button>
      <button onClick={() => setCents(200)}>Set $2</button>
      <button onClick={resetCents}>Reset</button>
    </>
  )
}
```

### Examples

<Codesandbox id="41c0s" />


Resettable


# No Suspense

> The content of this page would be easier if you have taken a look on the [basics/async](../basics/async.md) part of the docs.

Sometimes we need to wrap our components in suspense to use asynchronous atoms. Two kinds of atoms need Suspense.

- Derived async atoms (async `read` function)
- Asynchronous actions (async `write`)

But sometimes we're not allowed to wrap our components in Suspense, So we're going to do some hacks below and and make our async atoms synchronous.

## Async `read`

Check this derived async atom:

```tsx
const urlAtom = atom('https://json.host.com')
const fetchUrlAtom = atom(async (get) => {
  const response = await fetch(get(urlAtom))
  return await response.json()
})
```

It needs Suspense because the `read` function returns a promise(async function).

We shouldn't return a promise if we don't need it to suspend, so we have to change the structure slightly.

Here's the new code.

```tsx
const fetchResultAtom = atom({ loading: true, error: null, data: null })
const runFetchAtom = atom(
  (get) => get(fetchResultAtom),
  (_get, set, url) => {
    const fetchData = async () => {
      set(fetchResultAtom, (prev) => ({ ...prev, loading: true }))
      try {
        const response = await fetch(url)
        const data = await response.json()
        set(fetchResultAtom, { loading: false, error: null, data })
      } catch (error) {
        set(fetchResultAtom, { loading: false, error, data: null })
      }
    }
    fetchData()
  }
)
runFetchAtom.onMount = (runFetch) => {
  runFetch('https://json.host.com')
}

const Component = () => {
  const [result] = useAtom(runFetchAtom)

  console.log(result) // { loading: ..., error: ..., data: ... }
  return <div>...</div>
}
```

## Async `write`

The original code is:

```tsx
const fetchCountAtom = atom(
  (get) => get(countAtom),
  async (_get, set, url) => {
    const response = await fetch(url)
    set(countAtom, (await response.json()).count)
  }
)
```

The `write` function (2nd arg) returns a promise, which will suspend.

We just need to make it synchronous and returns nothing, just like this:

```tsx
const fetchCountAtom = atom(
  (get) => get(countAtom),
  (_get, set, url) => {
    const fetchData = async () => {
      const response = await fetch(url)
      set(countAtom, (await response.json()).count)
    }
    fetchData()
  }
)
```


No Suspense


# Atoms in atom

`atom()` creates an atom config, which is an object, but it doesn't hold a value.
Atom configs don't have string keys and we identify them with referential equality.
In other words, we can use an atom config like a key.

## Storing an atom config in useState

First things first, we can store an atom config in useState.

```jsx
const Component = ({ atom1, atom2 }) => {
  const [selectedAtom, setSelectedAtom] = useState(atom1)
  const [value] = useAtom(selectedAtom)
  return (
    <div>
      Selected value: {value}
      <button onClick={() => setSelectedAtom(atom1)}>Select an atom</button>
      <button onClick={() => setSelectedAtom(atom2)}>Select another atom</button>
    </div>
  )
}
```

Note that we can pass atoms configs as props.

It might not make any sense, but we could create an atom config on demand.

```jsx
const Component = () => {
  const [currentAtom, setCurrentAtom] = useState(() => atom(0))
  const [count, setCount] = useAtom(currentAtom)
  return (
    <div>
      Count: {count} <button onClick={() => setCount((c) => c + 1)}>+1</button>
      <button onClick={() => setCurrentAtom(atom(0))}>Create new</button>
    </div>
  )
}
```

## Storing an atom config in atom

Likewise, we can store an atom confing as a value of another atom.

```jsx
const firstNameAtom = atom('Tanjiro')
const lastNameAtom = atom('Kamado')

const showingNameAtom = atom(firstNameAtom)

const Component = () => {
  const [nameAtom, setNameAtom] = useAtom(showingNameAtom)
  const [name] = useAtom(nameAtom)
  return (
    <div>
      Name: {name}
      <button onClick={() => setNameAtom(firstNameAtom)}>Show First Name</button>
      <button onClick={() => setNameAtom(lastNameAtom)}>Show Last Name</button>
    </div>
  )
}
```

It's possible to create a derived atom.

```jsx
const derivedNameAtom = atom(get) => {
  const nameAtom = get(showingNameAtom)
  return get(nameAtom)
})

// Or shoter version
const derivedNameAtom = atom(get) => get(get(showingNameAtom)))
```

To avoid confusing what is in atoms, naming atoms explicitly would be important.
Also, TypeScript type information would be helpful.

## Storing an array of atom configs in atom

Finally, the atoms in atom pattern is to store an array of atom config into an atom.

```jsx
const countsAtom = atom([atom(1), atom(2), atom(3)])

const Counter = ({ countAtom }) => {
  const [count, setCount] = useAtom(countAtom)
  return (
    <div>
      {count} <button onClick={() => setCount((c) => c + 1)}>+1</button>
    </div>
  )
}

const Parent = () => {
  const [counts, setCounts] = useAtom(countsAtom)
  const addNewCount = () => {
    const newAtom = atom(0)
    setCounts((prev) => [...prev, newAtom])
  }
  return (
    <div>
      {counts.map((countAtom) => (
        <Counter countAtom={countAtom} key={countAtom} />
      ))}
      <button onClick={addNewCount}>Add</button>
    </div>
  )
}
```

The benefit of this approach is, if you increment a count,
only the corresponding Counter component re-renders and no other components re-render.

It is important to note that `anAtom.toString()` return a unique id, which can be used for `key` in map.

### Hint for TypeScript users

```tsx
<Counter countAtom={countAtom} key={`${countAtom}`} />
```

## Storing a map of atom configs in atom

Likewise, we can store an object map instead of an array.

```jsx
const pricesAtom = atom({
  apple: atom(15),
  orange: atom(12),
  pineapple: atom(25),
})

const Fruit = ({ name, priceAtom }) => {
  const [price] = useAtom(priceAtom)
  return (
    <div>
      {name}: {price}
    </div>
  )
}

const Parent = () => {
  const [prices] = useAtom(pricesAtom)
  return (
    <div>
      {Object.keys(prices).map((name) => (
        <Fruit name={name} priceAtom={prices[name]} key={name} />
      ))}
    </div>
  )
}
```


Atoms in atom


We echo the [guiding principles of Testing library](https://testing-library.com/docs/guiding-principles/):

- "The more your tests resemble the way your software is used, the more confidence they can give you."

We encourage you to write tests, like the user would interact with your atoms and components,
therefore treating Jotai as an implementation detail.

Here's an example using [React testing library](https://github.com/testing-library/react-testing-library):

`Counter.tsx`:

```tsx
import { atom, useAtom } from 'jotai'

const countAtom = atom(0)

export function Counter() {
  const [count, setCount] = useAtom(countAtom)
  return (
    <h1>
      <p>{count}</p>
      <button onClick={() => setCount((c) => c + 1)}>one up</button>
    </h1>
  )
}
```

`Counter.test.tsx`:

```tsx
import React from 'react'
import { render, screen } from '@testing-library/react'
import { Counter } from './Counter'

test('should increment counter', () => {
  // Arrange
  render(<Counter />)

  const counter = screen.getByText('0')
  const incrementButton = screen.getByText('one up')
  // Act
  fireEvent.click(incrementButton)
  // Assert
  expect(counter.textContent).toEqual('1')
})
```

## Custom hooks

If you have complex atoms, sometimes you want to test them in isolation.

For that, you can use [React Hooks Testing Library](https://github.com/testing-library/react-hooks-testing-library).
Here's an example below:

`countAtom.ts`:

```tsx
import { useAtom } from 'jotai'
import { atomWithReducer } from 'jotai/utils'

const reducer = (state: number, action?: 'INCREASE' | 'DECREASE') => {
  switch (action) {
    case 'INCREASE':
      return state + 1
    case 'DECREASE':
      return state - 1
    case undefined:
      return state
  }
}
export const countAtom = atomWithReducer(0, reducer)
```

`countAtom.test.ts`:

```tsx
import { renderHook, act } from '@testing-library/react-hooks'
import { useAtom } from 'jotai'
import { countAtom } from './countAtom'

test('should increment counter', () => {
  const { result } = renderHook(() => useAtom(countAtom))

  act(() => {
    result.current[1]('INCREASE')
  })

  expect(result.current[0]).toBe(1)
})
```



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

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

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


ContactShadows


> 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/](gltf.pmnd.rs) and drop your `GLTF`, after that you should see something like:

![gltfjsx](./gltfjsx.png)

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

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

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

export default function Model(props) {
  const 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 barebones 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


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

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


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


## Install

You have to install `immer` to access this bundle and its functions.

```
npm install immer
# or
yarn add immer
```

## atomWithImmer

`atomWithImmer` creates a new atom similar to the regular [`atom`](/jotai/api/core#atom) [atom] with a different `writeFunction`. In this bundle, we don't have read-only atoms, because the point of these functions is the immer produce(mutability) function.
The signature of writeFunction is `(get, set, update: (draft: Draft<Value>) => void) => void`.

```js
import { useAtom } from 'jotai'
import { atomWithImmer } from 'jotai/immer'

const countAtom = atomWithImmer(0)

const Counter = () => {
  const [count] = useAtom(countAtom)
  return <div>count: {count}</div>
}

const Controls = () => {
  const [, setCount] = useAtom(setCountAtom)
  // setCount === update : (draft: Draft<Value>) => void
  const inc = () => setCount((c) => (c = c + 1))
  return <button onClick={inc}>+1</button>
}
```

### Examples

Check examples with atomWithImmer:

<Codesandbox id="8zrqs" />

## withImmer

`withImmer` takes an atom and returns a derived atom, same as `atomWithImmer` it has a different `writeFunction`.

```js
import { useAtom, atom } from 'jotai'
import { withImmer } from 'jotai/immer'

const primitiveAtom = atom(0)
const countAtom = withImmer(primitiveAtom)

const Counter = () => {
  const [count] = useAtom(countAtom)
  return <div>count: {count}</div>
}

const Controls = () => {
  const [, setCount] = useAtom(setCountAtom)
  // setCount === update : (draft: Draft<Value>) => void
  const inc = () => setCount((c) => (c = c + 1))
  return <button onClick={inc}>+1</button>
}
```

## useImmerAtom

This hook takes an atom and replaces the atom's `writeFunction` with the new immer-like `writeFunction` like the previous helpers.

```jsx
import { useAtom } from 'jotai'
import { useImmerAtom } from 'jotai/immer'

const primitiveAtom = atom(0)

const Counter = () => {
  const [count] = useImmerAtom(primitiveAtom)
  return <div>count: {count}</div>
}

const Controls = () => {
  const [, setCount] = useImmerAtom(primitiveAtom)
  // setCount === update : (draft: Draft<Value>) => void
  const inc = () => setCount((c) => (c = c + 1))
  return <button onClick={inc}>+1</button>
}
```

It would be better if you don't use `withImmer` and `atomWithImmer` with `useImmerAtom` because they provide the immer-like `writeFunction` and we don't need to create a new one.

## Codesandbox

A good example of this bundle in [codesandbox](https://codesandbox.io/s/immer-jotai-doc-ms9pv?file=/src/App.tsx).

<Codesandbox id="ms9pv" />


Immer


## Install

You have to install `optics-ts` to access this bundle and its functions.

```
npm install optics-ts
# or
yarn add optics-ts
```

## focusAtom

`focusAtom` creates a new atom, based on the focus that you pass to it. This creates a derived atom that will focus on the specified part of the atom,
and when the derived atom is updated, the derivee is notified of the update, and the equivalent update is done on the derivee.

See this:

```typescript
const baseAtom = atom({ a: 5 }) // PrimitiveAtom<{a: number}>
const derivedAtom = focusAtom(baseAtom, (optic) => optic.prop('a')) // PrimitiveAtom<number>
```

So basically, we started with a `PrimitiveAtom<{a: number}>`, which has a getter and a setter, and then used `focusAtom` to zoom in on the `a`-property of
the `baseAtom`, and got a `PrimitiveAtom<number>`. What is noteworthy here is that this `derivedAtom` is not only a getter, it is also a setter. If `derivedAtom` is updated, then equivalent update is done on the `baseAtom`.

The example below is simple, but it's a starting point. `focusAtom` supports many kinds of optics, including `Lens`, `Prism`, `Isomorphism`.

To see more advanced optics, please see the example at: https://github.com/akheron/optics-ts

### Example

```jsx
import { atom } from 'jotai'
import { focusAtom } from 'jotai/optics'

const objectAtom = atom({ a: 5, b: 10 })
const aAtom = focusAtom(objectAtom, (optic) => optic.prop('a'))
const bAtom = focusAtom(objectAtom, (optic) => optic.prop('b'))

const Controls = () => {
  const [a, setA] = useAtom(aAtom)
  const [b, setB] = useAtom(aAtom)
  return (
    <div>
      <span>Value of a: {a}</span>
      <span>Value of b: {b}</span>
      <button onClick={() => setA((oldA) => oldA + 1)}>Increment a</button>
      <button onClick={() => setA((oldB) => oldB + 1)}>Increment b</button>
    </div>
  )
}
```


This doc describes `jotai/optics` bundle.

Optics


## Install

You have to install `react-query` to access this bundle and its functions.

```
yarn add react-query
```

## atomWithQuery

`atomWithQuery` creates a new atom with React Query. This function helps you use both atoms features and `useQuery` features in a single atom.

```js
import { useAtom } from 'jotai'
import { atomWithQuery } from 'jotai/query'

const idAtom = atom(1)
const userAtom = atomWithQuery((get) => ({
  queryKey: ['users', get(idAtom)],
  queryFn: async ({ queryKey: [, id] }) => {
    const res = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`)
    return res.json()
  },
}))

const UserData = () => {
  const [data] = useAtom(userAtom)
  return <div>{JSON.stringify(data)}</div>
}
```

### Examples

#### Basic demo

<Codesandbox id="ij2sd" />

#### Hackernews

<Codesandbox id="u4sli" />


Query


This doc describes `jotai/xstate` bundle.

Jotai's state management is privimite and flexible,
but that sometimes means too free.
XState is a sophisticated library to provide
a better and safer abstraction for state management.

## Install

You have to install `xstate` to access this bundle and its functions.

```
npm install xstate
# or
yarn add xstate
```

## atomWithMachine

`atomWithMachine` creates a new atom with XState machine.
It receives a function `getMachine` to create a new machine.
`getMachine` is invoked at the first use with `get` argument,
with which you can read other atom values.

```js
import { useAtom } from 'jotai'
import { atomWithMachine } from 'jotai/xstate'
import { assign, createMachine } from 'xstate'

const createEditableMachine = (value: string) =>
  createMachine <
  { value: string } >
  {
    id: 'editable',
    initial: 'reading',
    context: {
      value,
    },
    states: {
      reading: {
        on: {
          dblclick: 'editing',
        },
      },
      editing: {
        on: {
          cancel: 'reading',
          commit: {
            target: 'reading',
            actions: assign({
              value: (_, { value }) => value,
            }),
          },
        },
      },
    },
  }

const defaultTextAtom = atom('edit me')
const editableMachineAtom = atomWithMachine((get) =>
  // `get` is available only for initializing a machine
  createEditableMachine(get(defaultTextAtom))
)

const Toggle: React.FC = () => {
  const [state, send] = useAtom(editableMachineAtom)

  return (
    <div>
      {state.matches('reading') && <strong onDoubleClick={send}>{state.context.value}</strong>}
      {state.matches('editing') && (
        <input
          autoFocus
          defaultValue={state.context.value}
          onBlur={(e) => send({ type: 'commit', value: e.target.value })}
          onKeyDown={(e) => {
            if (e.key === 'Enter') {
              send({ type: 'commit', value: e.target.value })
            }
            if (e.key === 'Escape') {
              send('cancel')
            }
          }}
        />
      )}
      <br />
      <br />
      <div>
        Double-click to edit. Blur the input or press <code>enter</code> to commit. Press{' '}
        <code>esc</code> to cancel.
      </div>
    </div>
  )
}
```

### Examples

Check examples with atomWithMachine:

<Codesandbox id="gxwnx" />


This doc describes `jotai/xstate` bundle.

XState


Jotai's state resides in React, but sometimes it would be nice
to interact with the world outside React.

Valtio provides a proxy interface that can be used to store some values
and sync with atoms in Jotai.

This only uses the vanilla api of valtio.

## Install

You have to install `valtio` to access this bundle and its functions.

```
npm install valtio
# or
yarn add valtio
```

## atomWithProxy

`atomWithProxy` creates a new atom with valtio proxy.
It's two-way binding and you can change the value from both ends.

```js
import { useAtom } from 'jotai'
import { atomWithProxy } from 'jotai/valtio'
import { proxy } from 'valtio/vanilla'

const proxyState = proxy({ count: 0 })
const stateAtom = atomWithProxy(proxyState)
const Counter: React.FC = () => {
  const [state, setState] = useAtom(stateAtom)

  return (
    <>
      count: {state.count}
      <button onClick={() => setState((prev) => ({ ...prev, count: prev.count + 1 }))}>
        button
      </button>
    </>
  )
}
```

### Examples

<Codesandbox id="f5u4l" />


This doc describes `jotai/valtio` bundle.

Valtio


Jotai's state resides in React, but sometimes it would be nice
to interact with the world outside React.

Zustand provides a store interface that can be used to hold some values
and sync with atoms in Jotai.

This only uses the vanilla api of zustand.

## Install

You have to install `zustand` to access this bundle and its functions.

```
npm install zustand
# or
yarn add zustand
```

## atomWithStore

`atomWithStore` creates a new atom with zustand store.
It's two-way binding and you can change the value from both ends.

```js
import { useAtom } from 'jotai'
import { atomWithStore } from 'jotai/zustand'
import create from 'zustand/vanilla'

const store = create(() => ({ count: 0 }))
const stateAtom = atomWithStore(store)
const Counter: React.FC = () => {
  const [state, setState] = useAtom(stateAtom)

  return (
    <>
      count: {state.count}
      <button onClick={() => setState((prev) => ({ ...prev, count: prev.count + 1 }))}>
        button
      </button>
    </>
  )
}
```

### Examples

<Codesandbox id="c6zi9" />


This doc describes `jotai/zustand` bundle.

Zustand


Jotai's state resides in React, but sometimes it would be nice
to interact with the world outside React.

Redux provides a store interface that can be used to store some values
and sync with atoms in Jotai.

## Install

You have to install `redux` to access this bundle and its functions.

```
npm install redux
# or
yarn add redux
```

## atomWithStore

`atomWithStore` creates a new atom with redux store.
It's two-way binding and you can change the value from both ends.

```js
import { useAtom } from 'jotai'
import { atomWithStore } from 'jotai/redux'
import { createStore } from 'redux'

const initialState = { count: 0 }
const reducer = (state = initialState, action: { type: 'INC' }) => {
  if (action.type === 'INC') {
    return { ...state, count: state.count + 1 }
  }
  return state
}
const store = createStore(reducer)
const storeAtom = atomWithStore(store)

const Counter: React.FC = () => {
  const [state, dispatch] = useAtom(storeAtom)

  return (
    <>
      count: {state.count}
      <button onClick={() => dispatch({ type: 'INC' })}>button</button>
    </>
  )
}
```

### Examples

<Codesandbox id="cmlu5" />


Redux


## Install

You have to install `@urql/core` and `wonka` to access this bundle and its functions.

```
yarn add @urql/core wonka
```

## atomWithQuery

`atomWithQuery` creates a new atom with a query. It internally uses [client.query](https://formidable.com/open-source/urql/docs/api/core/#clientquery).

```js
import { useAtom } from 'jotai'
import { createClient } from "@urql/core";
import { atomWithQuery } from 'jotai/urql'

const client = createClient({ url: "..." });

const idAtom = atom(1)
const userAtom = atomWithQuery(
  (get) => ({
    query: '{ user { first_name last_name } }',
    variables: { id: get(idAtom) },
  }),
  () => client,
)

const UserData = () => {
  const [{ data }] = useAtom(userAtom)
  return <div>{JSON.stringify(data)}</div>
}
```

### Examples

#### Basic demo

<Codesandbox id="zujf6" />

## atomWithMutation

`atomWithMutation` creates a new atom with a mutation. It internally uses [client.mutation](https://formidable.com/open-source/urql/docs/api/core/#clientmutation).

```js
import { useAtom } from 'jotai'
import { createClient } from "@urql/core";
import { atomWithMutation } from 'jotai/urql'

const client = createClient({ url: "..." });

const fooAtom = atomWithMutation(
  () => 'mutation Foo { text }',
  () => client,
)

const FooData = () => {
  const [{ data }, mutate] = useAtom(fooAtom)
  return <div>{JSON.stringify(data)} <button onClick={mutate}>Click me</button></div>
}
```

### Examples

TODO

## atomWithSubscription

`atomWithSubscription` creates a new atom with a mutation. It internally uses [client.subscription](https://formidable.com/open-source/urql/docs/api/core/#clientsubscription).

```js
import { useAtom } from 'jotai'
import { createClient } from "@urql/core";
import { atomWithSubscription } from 'jotai/urql'

const client = createClient({ url: "..." });

const fooAtom = atomWithSubscription(
  () => 'subscription Foo { text }',
  () => client,
)

const FooData = () => {
  const [{ data }] = useAtom(fooAtom)
  return <div>{JSON.stringify(data)}</div>
}
```

### Examples

TODO


URQL


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

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

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


Center


> 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 React, { 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, 100, 100]} />
        <meshStandardMaterial />
      </mesh>
    </>
  )
}

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

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

```jsx
<sphereGeometry args={[1, 100, 100]} map={colorMap} />
```

Awesome! That works but we have a lot more textures to import and do we have to create a diffent 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 play with the sandbox and see how it looks:

<Codesandbox id="rusfd" />


Loading Textures


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

`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


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


> All of the examples and descriptions below are based on this [codesandbox](https://codesandbox.io/s/zealous-sun-f2qnl?file=/src/App.tsx), so it will give you a better understanding if you check it out along these examples.

Sometimes we have big data we need to keep into atoms, we may need to change that data in some levels, or we need to use part of that data, but we can't listen to all these changes or use all that data for just a specific part.

Consider this example:

```jsx
const initialData = {
  people: [
    {
      name: 'Luke Skywalker',
      information: { height: 172 },
      siblings: ['John Skywalker', 'Doe Skywalker'],
    },
    {
      name: 'C-3PO',
      information: { height: 167 },
      siblings: ['John Doe', 'Doe John'],
    },
  ],
  films: [
    {
      title: 'A New Hope',
      planets: ['Tatooine', 'Alderaan'],
    },
    {
      title: 'The Empire Strikes Back',
      planets: ['Hoth'],
    },
  ],
  info: {
    tags: ['People', 'Films', 'Planets', 'Titles'],
  },
}
```

## `focusAtom`

> `focusAtom` creates a new atom, based on the focus that you pass to it. [jotai/optics](/jotai/api/optics#focus-atom)

We use this utility to focus an atom and create an atom of a specific part of the data. For example we may need to consume the people property of the above data, Here's how we do it.

```jsx
import { atom } from 'jotai'
import { focusAtom } from 'jotai/optics'

const dataAtom = atom(initialData)

const peopleAtom = focusAtom(dataAtom, (optic) => optic.prop('people'))
```

`focusAtom` returns `WritableAtom` which means it's possible to change the `peopleAtom` data.

If we change the `film` property of the above data example, the `peopleAtom` won't cause us a re-render, so that's one of the points of using `focusAtom`.

## `splitAtom`

> The `splitAtom` utility is useful, when you want to get an atom for each element in a list. [jotai/utils](/jotai/api/utils#split-atom)

We use this utility for atoms that return arrays as their values, for example the `peopleAtom` we made above returns the people property array, so we can return an atom for each item of that array. If the array atom is writable, `splitAtom` returned atoms are going to be writable, if the array atom is read-only, items atoms are going to be read-only too.

```jsx
import { splitAtom } from 'jotai/utils'

const peopleAtomsAtom = splitAtom(peopleAtom)
```

And that's how we use it in components.

```jsx
const People = () => {
  const [peopleAtoms] = useAtom(peopleAtomsAtom)
  return (
    <div>
      {peopleAtoms.map((personAtom) => (
        <Person personAtom={personAtom} key={`${personAtom}`} />
      ))}
    </div>
  )
}
```

## `selectAtom`

> This function creates a derived atom whose value is a function of the original atom's value. [jotai/utils](/jotai/api/utils#select-atom)

This utility is similar to `focusAtom`, but we use it when we have a read-only atom to select part of it, and it always returns a read-only atom.

Assume we want to consume the info data, and its data is always unchangeable, so we can make a read-only atom from it and select that created atom.

```jsx
// first we create a read-only atom based on initialData.info
const readOnlyInfoAtom = atom((get) => get(dataAtom).info)
```

Then we can going to consume it in our component:

```jsx
import { atom, useAtom } from 'jotai'
import { selectAtom, splitAtom } from 'jotai/utils'

const Tags: React.FC = () => {
  const tagsAtom = selectAtom(readOnlyInfoAtom, (s) => s.tags)
  const tagsAtomsAtom = splitAtom(tagsAtom)
  const [tagAtoms] = useAtom(tagsAtomsAtom)
  return (
    <div>
      {tagAtoms.map((tagAtom) => (
        <Tag key={`${tagAtom}`} tagAtom={tagAtom} />
      ))}
    </div>
  )
}
```


Large objects


## `atomWithToggle`

> `atomWithToggle` creates a new atom with a boolean as initial state & a setter function to toggle it.

This avoids the boilerplate of having to setup another atom just to update the state of the first.

```ts
import { WritableAtom, atom } from 'jotai'

export function atomWithToggle(initialValue?: boolean): WritableAtom<boolean, boolean | undefined> {
  const anAtom = atom(initialValue, (get, set, nextValue?: boolean) => {
    const update = nextValue ?? !get(anAtom)
    set(anAtom, update)
  })

  return anAtom
}
```

An optional initial state can be provided as first argument.

The setter function can have an optional arg to force a particular state (if you want to make a setActive function out of it for example).

Here is how it's used.

```ts
import { atomWithToggle } from 'XXX'

// will have an initial value set to true
const isActiveAtom = atomWithToggle(true)
```

And in a component :

```tsx
const Toggle = () => {
  const [isActive, toggle] = useAtom(isActiveAtom)

  return (
    <>
      <button onClick={() => toggle()}>isActive: {isActive ? 'yes' : 'no'}</button>
      <button onClick={() => toggle(true)}>force true</button>
      <button onClick={() => toggle(false)}>force false</button>
    </>
  )
}
```

## `atomWithToggleAndStorage`

> `atomWithToggleAndStorage` does the same as [`atomWithToggle`](#atomWithToggle) but also persist the state anytime it changes in given storage using [`atomWithStorage`](/jotai/api/utils#atomWithStorage).

Here is the source :

```ts
import { WritableAtom, atom } from 'jotai'
import { atomWithStorage } from 'jotai/utils'

export function atomWithToggleAndStorage(
  key: string,
  initialValue?: boolean,
  storage?: any
): WritableAtom<boolean, boolean | undefined> {
  const anAtom = atomWithStorage(key, initialValue, storage)
  const derivedAtom = atom(
    (get) => get(anAtom),
    (get, set, nextValue?: boolean) => {
      const update = nextValue ?? !get(anAtom)
      set(anAtom, update)
    }
  )

  return derivedAtom
}
```

And how it's used :

```ts
import { atomWithToggleAndStorage } from 'XXX'

// will have an initial value set to false & be stored in localStorage under the key "isActive"
const isActiveAtom = atomWithToggleAndStorage('isActive')
```

The usage in a component is also the same as [`atomWithToggle`](#atomWithToggle).


Atom creators


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

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

You can override styles, too.

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

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


Loader


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


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


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


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

```jsx
const curveRef = useRef()

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

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

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


CurveModifier


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://www.react-spring.io/docs/hooks/api).

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


## 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](http://localhost:3000/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](/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


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 positionned 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 watchs 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?

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

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

Stage


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



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      | `{}`                                                     |
| camera          | Props that go into the default camera, or your own `THREE.Camera`  | `{ fov: 75, near: 0.1, far: 1000, position: [0, 0, 5] }` |
| shadows         | Props that go into `gl.shadowMap`, can also be set true for `PCFsoft`  | `false`                                                  |
| raycaster       | Props that go into the default raycaster                           | `{}`                                                     |
| vr              | Switches renderer to VR mode, then uses `gl.setAnimationLoop`        | `false`                                                  |
| mode            | React mode: legacy, blocking, concurrent                           | `blocking`                                               |
| frameloop       | Render mode: always, demand, never                                 | `always`                                                 |
| resize          | Resize config, see react-use-measure's options                     | `{ scroll: true, debounce: { scroll: 50, resize: 0 } }`  |
| orthographic    | Creates an orthographic camera                                     | `false`                                                  |
| dpr             | Pixel-ratio, use `window.devicePixelRatio`, or automatic: [min, max] | `undefined`                                              |
| linear          | Switch off automatic sRGB encoding and gamma correction            | `false`                                                  |
| flat            | Use `THREE.NoToneMapping` instead of `THREE.ACESFilmicToneMapping` | `false`                                                  |
| onCreated       | Callback after the canvas has rendered (but not yet committed)     | `(state) => {}`                                          |
| onPointerMissed | Response for pointer clicks that have missed any target            | `(event) => {}`                                          |

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

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

### Defaults that the canvas component sets up

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

- antialias=true
- alpha=true
- powerPreference="high-performance"
- setClearAlpha(0)
- A `THREE.Perspective` camera
- A `THREE.Orthographic` cam if `orthographic` is true
- A `THREE.PCFSoftShadowMap` if `shadows` is true
- A `THREE.Scene` (into which all the JSX is rendered) and a `THREE.Raycaster`
- A [resize observer](https://github.com/react-spring/react-use-measure)

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

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


The Canvas object is your portal into three.js.

Canvas


## 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](/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


### 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 curor 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 positionned 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 whange while the cursor is in the hole of the donut.

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


Gotchas


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

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

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



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


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

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

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 objects that are normally not part of the scene, and attaching

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

Using the `attach` property objects bind to their parent and are taken off once they unmount.

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

```jsx
<mesh>
  <meshBasicMaterial attach="material">
```

You can nest primitive objects, too:

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

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

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

<Hint>
  As of version 5 all elements ending with "Material" receive attach="material", and all elements
  ending with "Geometry" receive attach="geometry" automatically. Of course you can still overwrite
  it, but it isn't necessary to type out any longer.
</Hint>

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

### 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={[1 / size.width, 1 / size.height]} />
```

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


All the effective ways of using React Three Fiber

Objects, properties and constructor arguments


## 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](http://localhost:3000/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](/docs/hooks/api) 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


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

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


AdaptiveDpr


`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                 // Initial-click delta
}) => ...
```

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

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

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

### Event propagation (bubbling)

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

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

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

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

### Pointer capture

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

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

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

```jsx
onPointerDown={e => {
  // Only the mesh closest to the camera will be processed
  e.stopPropagation()
  // You may optionally capture the target
  e.target.setPointerCapture(e.pointerId)
}}
onPointerUp={e => {
  e.stopPropagation()
  // Optionally release capture
  e.target.releasePointerCapture(e.pointerId)
}}
```


Events

## 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](/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](/hooks/use-transition#keys) for more information                                                                                                      |
| key      | single item       | only use if you're passing a single item to `useTransition` see [keys](/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](/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>

FlyControls