## 1. Project Overview & Quickstart (pmndrs/react-spring)
## File: README.md
react-spring
A spring-physics first animation library giving you flexible tools to confidently cast your ideas
`react-spring` is a cross-platform spring-physics first animation library.
It's as simple as:
```jsx
const styles = useSpring({
from: {
opacity: 0
},
to: {
opacity: 1
}
})
```
Just a small bit about us:
- **Cross-Platform**: We support `react-dom` and `react-three-fiber`.
- **Versatile**: Be declarative with your animations or if you prefer, imperative.
- **Spring-Physics First**: By default animation use springs for fluid interactivity, but we support durations with easings as well.
There's a lot more to be had! Give it a try and find out.
## Getting Started
### β‘οΈ Jump Start
```shell
# Install the target you need
npm install @react-spring/web
# or, for react-three-fiber
npm install @react-spring/three
```
```jsx
import { animated, useSpring } from '@react-spring/web'
const FadeIn = ({ isVisible, children }) => {
const styles = useSpring({
opacity: isVisible ? 1 : 0,
y: isVisible ? 0 : 24,
})
return {children}
}
```
It's as simple as that to create scroll-in animations when value of `isVisible` is toggled.
### π Documentation and Examples
More documentation on the project can be found [here](https://www.react-spring.dev).
Pages contain their own [examples](https://react-spring.dev/hooks/use-spring#demos) which you can check out there, or [open in codesandbox](https://codesandbox.io/s/github/pmndrs/react-spring/tree/main/demo/src/sandboxes/card) for a more in-depth view!
---
## π£ What others say
## Used by
[](https://nextjs.org/)
[](https://codesandbox.io/)
[](https://aragon.org/)
And [many others...](https://github.com/pmndrs/react-spring/network/dependents)
## Backers
Thank you to all our backers! π If you want to join them here, then consider contributing to our [Opencollective](https://opencollective.com/pmndrs).
## Contributors
This project exists thanks to all the people who contribute.
---
## File: docs/app/routes/docs._index.mdx
---
meta:
title: Overview | React Spring
'og:title': Overview | React Spring
'twitter:title': Overview | React Spring
'description': Documentation overview for React Spring.
'og:description': Documentation overview for React Spring.
'twitter:description': Documentation overview for React Spring.
'og:url': https://www.react-spring.dev/docs
'twitter:url': https://www.react-spring.dev/docs
sidebar_position: 1
noSubnav: true
---
import { formatFrontmatterToRemixMeta } from '../helpers/meta'
export const meta = formatFrontmatterToRemixMeta(frontmatter)
# Overview
Welcome to the `react-spring` docs site!
import { NAV_TILES } from '../data/fixtures'
import { NavigationGrid } from '../components/Grids/NavigationGrid'
## What is this?
Our old documentation was lacking in features & clarity. So, based on
community feedback, we've made an endeavor to improve our documentation with a
few key differences:
- We want to explain more of our codebase conceptually e.g what is an `animated`
component
- All our content will be searchable so no more running around in the dark
- Step-by-step tutorials on how to achieve common use-cases
## How can I help?
Thank you for being interested in helping! It means a lot, if you want to provide
generic feedback please do so [here](https://github.com/pmndrs/react-spring/discussions/1931).
Otherwise, each page has it's own feedback button you can use to give an up or down
vote, followed by the option to then add written feedback.
If you're interested in adding an example to the site then why not check out the specific
[contributing guide](https://github.com/pmndrs/react-spring/tree/main/demo/CONTRIBUTING.md).
---
## File: docs/app/routes/docs.advanced._index.mdx
---
meta:
title: Advanced API | React Spring
sidebar_position: 5
noPage: true
---
---
## File: docs/app/routes/docs.advanced.async-animations.mdx
---
meta:
title: Async Animations | React Spring
'og:title': Async Animations | React Spring
'twitter:title': Async Animations | React Spring
'og:description': An advanced guide to Async Animations and what they are in React Spring.
'twitter:description': An advanced guide to Async Animations and what they are in React Spring.
'og:url': https://www.react-spring.dev/docs/advanced/async-animations
'twitter:url': https://www.react-spring.dev/docs/advanced/async-animations
sidebar_position: 7
---
import { formatFrontmatterToRemixMeta } from '../helpers/meta'
export const meta = formatFrontmatterToRemixMeta(frontmatter)
# Async Animations
:::note
This is an advanced guide. If you're new to `react-spring`, you should start with the [getting started](/docs/getting-started) page
and become familar with the library before jumping into async animations.
:::
## Aren't all animations async?
Well technically in `react-spring` yes, you could consider animations to be async? The `start` function of a `Controller` is async and therefore
the `imperative api` is too, async. And then your styles are updated asynchronously... But that's not what this guide is referring too.
When we talk about async animations we refer to the ability to perform X amount of transformations with only one call of the APIs and each
animation chunk will finish before the other begins. If you look at the example below, this animation has only a config object, `loop` prop
and a `to` prop.
```tsx live=true showCode=false
import { useSpring, animated } from '@react-spring/web'
export default function MyComponent() {
const springs = useSpring({
from: { background: '#ff6d6d', y: -40, x: 0 },
to: [
{ x: 80, background: '#fff59a' },
{ y: 40, background: '#88DFAB' },
{ x: 0, background: '#569AFF' },
{ y: -40, background: '#ff6d6d' },
],
loop: true,
})
return (
)
}
```
## The `to` prop
If you've read any of the `component` pages, you'll know we accept a `to` prop, it's typically used as an object,
but alternatively, you can also use an array (chaining the animations) or a function (writing an animation script).
When you consider the options you have as to what you can pass to the `to` prop, you'll begin to understand how complicated
your animations _can_ be, it's then a matter of understand what you're trying to achieve and applying the best solution.
## Chaining animations
The array syntax is a middleground between total control of async animations and the simplicity of passing just an `object`.
Just like the `start` method of the imperative api, you don't need to reference every key for each update. Each update will fire
when the previous one has finished.
```tsx lines=6-11 live=true defaultOpen=true
import { useSpring, animated } from '@react-spring/web'
export default function MyComponent() {
const springs = useSpring({
from: { background: '#ff6d6d', y: -40, x: 0 },
to: [
{ x: 80, background: '#fff59a' },
{ y: 40, background: '#88DFAB' },
{ x: 0, background: '#569AFF' },
{ y: -40, background: '#ff6d6d' },
],
loop: true,
})
return (
)
}
```
## Writing animation scripts
When you need most control of your animation, it's best to write a `script` by providing a `function` to the `to` prop.
The function receives two arguments, the `next` function which accepts an object of updates, again similar to the start
method of the imperative API and a `cancel` function which works the same as the `stop` method of the `imperative API`.
This therefore allows you to cancel scripts at any time meaning you can react to external events & conditions.
For further reading, see [`imperative API`](/docs/advanced/spring-ref#stop).
```tsx lines=6-11 live=true defaultOpen=true
import { useSpring, animated } from '@react-spring/web'
export default function MyComponent() {
const springs = useSpring({
from: { background: '#ff6d6d', y: -40, x: 0 },
to: async (next, cancel) => {
await next({ x: 80, background: '#fff59a' })
await next({ y: 40, background: '#88DFAB' })
await next({ x: 0, background: '#569AFF' })
await next({ y: -40, background: '#ff6d6d' })
},
loop: true,
})
return (
)
}
```
---
## File: docs/app/routes/docs.advanced.config.mdx
---
meta:
title: Spring Configs | React Spring
'og:title': Spring Configs | React Spring
'twitter:title': Spring Configs | React Spring
'og:description': An advanced guide to the configs of Controllers, Components & SpringValues in React Spring.
'twitter:description': An advanced guide to the configs of Controllers, Components & SpringValues in React Spring.
'og:url': https://www.react-spring.dev/docs/advanced/config
'twitter:url': https://www.react-spring.dev/docs/advanced/config
sidebar_position: 1
---
import { formatFrontmatterToRemixMeta } from '../helpers/meta'
export const meta = formatFrontmatterToRemixMeta(frontmatter)
# Spring Configs
Part of a component's `configuration` argument, the `config` prop is an object
with many properties that can be used to customize & fine tune your animations.
It directly controls how your springs behave and can customized on a spring by
spring basis (e.g. `opacity` and `scale` could be different for one `useSpring` hook).
## Usage
### Basic Usage
Your most typical usage of the `config` prop is to edit the mass, friction and tension properties.
```jsx lines=7-11
import { useSpring, animated } from '@react-spring/web'
const MyComponent = () => {
const [springs, api] = useSpring(
() => ({
y: 0,
config: {
mass: 5,
friction: 120,
tension: 120,
},
}),
[]
)
return
}
```
### Config per SpringValue
The `config` prop can also be a function where the argument is the key of the
spring value, this is great if you want one spring to control many elements or
have properties behave in different ways like a smooth opacity change but a
bouncy scale.
```jsx lines=8-18
import { useSpring, animated } from '@react-spring/web'
const MyComponent = () => {
const [springs, api] = useSpring(
() => ({
backgroundColor: '#00ff00',
y: 0,
config: key => {
if (key === 'y') {
return {
mass: 5,
friction: 120,
tension: 120,
}
}
return {}
},
}),
[]
)
return
}
```
Returning an empty object will enforce the default config options:
`{ mass: 1, tension: 170, friction: 26 }`.
### Partial Updates
When using the spring `api` you can partially update your configs.
These partial configs are merged with the original config for each
call of the api.
```jsx lines=17-22
import { useSpring, animated } from '@react-spring/web'
const MyComponent = () => {
const [springs, api] = useSpring(
() => ({
y: 0,
config: {
mass: 5,
friction: 120,
tension: 120,
},
}),
[]
)
const handleClick = () => {
api.start({
y: 20,
config: {
friction: 10,
},
})
}
return
}
```
### Presets
Additionally to being able to configure your own spring, we export a
small selection of presets enclosed in the `config` named export.
```jsx
import { config } from '@react-spring/web'
```
The presets are:
import { DescriptiveList } from '../components/Text/List'
## Config Visualizer
```jsx live=true template=configPlayground showCode=false
import { useRef, useState } from 'react'
import { useSpring, animated } from '@react-spring/web'
import { useControls } from 'leva'
export default function Card() {
const cardRef = useRef(null)
const config = useControls({
mass: 1,
tension: 170,
friction: 26,
clamp: false,
precision: 0.01,
velocity: 0,
})
const [{ xys }, api] = useSpring(() => ({ xys: [0, 0, 1], config }), [config])
const handleMouseLeave = () =>
api.start({
xys: [0, 0, 1],
})
const handleMouseMove = e => {
const rect = cardRef.current.getBoundingClientRect()
api.start({
xys: calc(e.clientX, e.clientY, rect),
})
}
return (
)
}
const calc = (x, y, rect) => [
-(y - rect.top - rect.height / 2) / 5,
(x - rect.left - rect.width / 2) / 5,
1.4,
]
const trans = (x, y, s) =>
`perspective(600px) rotateX(${x}deg) rotateY(${y}deg) scale(${s})`
```
## Easings
Easings can **only** be used in conjunction with the `duration` property.
### Why Springs?
We think of animation in terms of time and curves, but that 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. Springs donβt have a defined curve or a set duration.
As Andy Matuschak (ex Apple UI-Kit developer) expressed β βAnimation APIs parameterized by duration
and curve are fundamentally opposed to continuous, fluid interactivity.β
### Available generic easings
All the following easings are part of the `easings` object imported like so:
```jsx
import { easings } from '@react-spring/web'
```
import { TableGeneric } from '../components/Tables/TablesConfig'
import { easingData } from '../data/fixtures'
### Steps easing
This unique easing function returns the standard `EasingFunction` a `config` object expects. Its still part
of the `easings` object but you need to set it up before passing.
```jsx
import { easings } from '@react-spring/web'
const MyComponent = () => {
const [springs, api] = useSpring(
() => ({
y: 0,
config: {
easing: easings.steps(5),
},
}),
[]
)
return
}
```
It can also take a `Direction` as a second argument, which can be either `start` or `end`. The signature
for the function is shown below:
```ts
export function steps(
steps: number,
direction: Direction = 'end'
): EasingFunction
```
## Reference
import { TablesConfiguration } from '../components/Tables/TablesConfig'
import { configData } from '../data/fixtures'
## Pitfalls
### My animation jumps at the end.
In some instances such as animating `threejs` the items can feel as if they skip the
last couple of frames. This is because the precision prop has a default value of `0.01`.
Try editing this value to be `0.0001` to resolve this.
### My animation is bouncing and I just want it to stop.
Sometimes you want a snapping feel so you create a sharp spring. When you animate the spring
the animation bounces around, this is because of the physics. An easy solution to this is to
set `clamp` to true. Your spring will stop animating at the point it hit's it's goal value.
---
## File: docs/app/routes/docs.advanced.controller.mdx
---
meta:
title: Controller | React Spring
'og:title': Controller | React Spring
'twitter:title': Controller | React Spring
'og:description': An advanced API guide to the Controller class in React Spring.
'twitter:description': An advanced API guide to the Controller class in React Spring.
'og:url': https://www.react-spring.dev/docs/advanced/controller
'twitter:url': https://www.react-spring.dev/docs/advanced/controller
sidebar_position: 3
---
import { formatFrontmatterToRemixMeta } from '../helpers/meta'
export const meta = formatFrontmatterToRemixMeta(frontmatter)
# Controller
Manages [`SpringValue`s](/docs/advanced/spring-value) for our spring hooks.
## Usage
Basic usage, the Controller class you initialise can be used as an [`imperative api`](/docs/concepts/imperative-api)
to control your `SpringValues`. Meanwhile you pass `Controller.springs` to your `animated` component.
```tsx
import { Component, createRef } from 'react'
import { Controller, animated } from '@react-spring/web'
class AnimatedComponent extends Component {
isShowing = createRef(false)
animations = new Controller({ opacity: 0 })
toggle = () => {
this.animations.start({ opacity: this.isShowing ? 1 : 0 })
this.isShowing = !this.isShowing
}
render() {
return (
<>
click
I will fade
)
}
}
```
### Constructor Arguments
Below is the arguments that can passed to the constructor of the `Controller` class.
```ts
const ControllerProps = {
ref,
from,
loop,
onStart,
onRest,
onChange,
onPause,
onResume,
onProps,
onResolve,
}
```
## Properties
import { TablesConfiguration } from '../components/Tables/TablesConfig'
import { CONTROLLER_PROPERTIES_DATA } from '../data/fixtures'
## Methods
### Get
Gets the current values of our springs.
```ts
get(): State & UnknownProps;
```
### Set
Set the current values without animating.
```ts
set(values: Partial): void;
```
### Update
Push an update onto the queue of each value.
```ts
update(props: ControllerUpdate | Falsy): this;
```
### Start
Start the queued animations for every spring, and resolve the returned promise once all queued
animations have finished or been cancelled. When you pass a queue (instead of nothing), that
queue is used instead of the queued animations added with the `update` method, which are left alone.
```ts
start(props?: OneOrMore> | null): AsyncResult;
```
### Stop
Stop all queued animations for every spring at the same time, or alternatively provide a selection
of keys that should be stopped.
```ts
stop(): this;
stop(keys: OneOrMore): this;
stop(cancel: boolean): this;
stop(cancel: boolean, keys: OneOrMore): this;
stop(keys?: OneOrMore): this;
stop(cancel: boolean, keys?: OneOrMore): this;
```
### Pause
Freeze the active animation in time.
```ts
pause(keys?: OneOrMore): this;
```
### Resume
Resume the animation if paused.
```ts
resume(keys?: OneOrMore): this;
```
### Each
Call a function once per spring value.
```ts
each(iterator: (spring: SpringValue, key: string) => void): void
```
---
## File: docs/app/routes/docs.advanced.events.mdx
---
meta:
title: Events | React Spring
'og:title': Events | React Spring
'twitter:title': Events | React Spring
'og:description': An advanced guide to the event system of Controllers, Components & SpringValues in React Spring.
'twitter:description': An advanced guide to the event system of Controllers, Components & SpringValues in React Spring.
'og:url': https://www.react-spring.dev/docs/advanced/events
'twitter:url': https://www.react-spring.dev/docs/advanced/events
sidebar_position: 2
---
import { formatFrontmatterToRemixMeta } from '../helpers/meta'
export const meta = formatFrontmatterToRemixMeta(frontmatter)
# Events
There are a handful of events you can use to react to the state of animation at certain points in time.
## Keys vs Springs
Every event function can either be a function on it's own or be an object to which it's keys correlate
to the keys of the spring:
```jsx line=5-6,15-19
useSpring(
() => ({
x: 0,
y: 0,
// onStart is called when the animation of the spring starts
onStart: () => console.log('the spring has started'),
}),
[]
)
useSpring(
() => ({
x: 0,
y: 0,
onStart: {
// onStart is called for each key when the animation starts
x: () => console.log('x key has started'),
y: () => console.log('y key has started'),
},
}),
[]
)
```
The latter form can be useful if for example you have different configs for different keys.
Or you want to do different events based on different keys, e.g. you want to imperatively
update an objects rotation based on the x key.
## onStart
Called when the animation begins.
:::warning
`onStart` is called after the first animation tick, this value is therefore considered dirty.
:::
```ts
type OnStart = (
result: AnimationResult,
spring: Controller | SpringValue,
item?: Item
) => void
```
## onChange
Called on every frame.
```ts
type OnChange = (
result: AnimationResult,
spring: Controller | SpringValue,
item?: Item
) => void
```
## onRest
Called when the animation comes to a stand-still.
```ts
type OnRest = (
result: AnimationResult,
spring: Controller | SpringValue,
item?: Item
) => void
```
## onPause
Called when the animation is paused.
```ts
type OnPause = (
result: AnimationResult,
spring: Controller | SpringValue,
item?: Item
) => void
```
## onResume
Called when the animation is resumed.
```ts
type OnResume = (
result: AnimationResult,
spring: Controller | SpringValue,
item?: Item
) => void
```
## onResolve
Called when the promise for the update is resolved.
```ts
type OnResolve = (
result: AnimationResult,
spring: Controller | SpringValue,
item?: Item
) => void
```
## onProps
Called after an animation is updated by new props, even if the animation remains idle.
```ts
type OnProps = (
props: {[key: string]: any}
spring: SpringValue,
) => void
```
## onDestroyed
Called after a transition item is unmounted.
```ts
type OnDestroyed = (
item: Item
key: string | number
) => void
```
## Typescript
```ts
interface AnimationResult {
// Type inference will solve this for you.
value: SpringValue | { [keyof SpringValues]: number} | number
finished: boolean
cancelled: boolean
}
```
### A note on `Item`
The `Item` argument is only present when using the relevant events within the [`useTransition`](/docs/components/use-transition) hook.
---
## File: docs/app/routes/docs.advanced.interpolation.mdx
---
meta:
title: Interpolation | React Spring
'og:title': Interpolation | React Spring
'twitter:title': Interpolation | React Spring
'og:description': An advanced guide to the interpolation API in React Spring.
'twitter:description': An advanced guide to the interpolation API in React Spring.
'og:url': https://www.react-spring.dev/docs/advanced/interpolation
'twitter:url': https://www.react-spring.dev/docs/advanced/interpolation
sidebar_position: 6
---
import { formatFrontmatterToRemixMeta } from '../helpers/meta'
export const meta = formatFrontmatterToRemixMeta(frontmatter)
# Interpolation
## What is one?
An interpolation typically is a function that takes a value returns another value. You can even map ranges
of values β numbers are typically required as the input range. So for example, if you want to animate a value
from 0 to 100, you can use an interpolation to map the range 0 to 1 to 0 to 100.
## Basic Usage
### Extending the `SpringValue`
The most common use of our interpolation is to convert the value of a `SpringValue` to another value. This is
done by using the `to` method.
```tsx lines=10
import { useSpring, animated } from '@react-spring/web'
function MyComponent() {
const props = useSpring({
from: { x: 0 },
to: { x: 360 },
})
return (
`rotateZ(${value}deg)`) }}
>
Hello World
)
}
```
### Using the `to` function
Similar to the example above, it's also possible to use our `to` function to convert `SpringValue`s.
```tsx lines=1,10
import { useSpring, animated, to } from '@react-spring/web'
function MyComponent() {
const props = useSpring({
from: { x: 0 },
to: { x: 360 },
})
return (
`rotateZ(${value}deg)`) }}
>
Hello World
)
}
```
## Advanced Usage
### Combining values
A more advanced use of our interpolation is to combine multiple `SpringValue`s. This normally requires the
use of our `to` function to create.
```tsx lines=1,10
import { animated, to, useSpring } from '@react-spring/web'
export default function MyComponent() {
const props = useSpring({
from: { x: 0, y: 0, z: 0 },
to: { x: 1, y: 1, z: 1 },
})
return (
`rotate3d(${x}, ${y}, ${z}, 45deg)`
),
}}
>
Hello World
)
}
```
### Ranges and Outputs
The `to` function also accepts a range of input values as the first argument and the output of that range.
Interpolations can be chained, as seen in the example below we change a value `0-1` to `0-360` and then
interpolate it to a rotateZ value.
```tsx lines=10
import { useSpring, animated } from '@react-spring/web'
function MyComponent() {
const props = useSpring({
from: { x: 0 },
to: { x: 1 },
})
return (
`rotateZ(${value}deg)`),
}}
>
Hello World
)
}
```
## Config
An interpolation can also take a config object as the second argument if using the `to` function or the first
argument when using the `to` method of a `SpringValue`.
import { TablesConfiguration } from '../components/Tables/TablesConfig'
import { INTERPOLATONS_DATA } from '../data/fixtures'
## Overriding the global to function
If you decide to, it is possible to override the global Interpolation factory which is what's called when `to` is used.
```ts
import { Globals } from '@react-spring/web'
Globals.assign({
to: (source, args) => new CustomInterpolation(source, args),
})
```
## Typescript
```ts
function to, Output>(
parents: Input,
interpolator: (...args: Interpolated) => Output
): Interpolation