0
# @react-spring/three
1

2
@react-spring/three provides seamless integration between react-spring's spring-physics animation system and React Three Fiber (R3F) for 3D scenes. It enables developers to animate Three.js objects, materials, and properties using react-spring's declarative API with spring physics.
3

4
## Package Information
5

6
- **Package Name**: @react-spring/three
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @react-spring/three @react-three/fiber three`
10
- **Peer Dependencies**: 
11
  - `@react-three/fiber` >= 6.0
12
  - `three` >= 0.126
13
  - `react` ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
14

15
## Core Imports
16

17
```typescript
18
import { animated, useSpring, useSpringValue } from "@react-spring/three";
19
```
20

21
For shorter syntax:
22

23
```typescript
24
import { a, useSpring } from "@react-spring/three";
25
```
26

27
## Basic Usage
28

29
```typescript
30
import { animated, useSpring } from "@react-spring/three";
31
import { Canvas } from "@react-three/fiber";
32

33
function AnimatedCube() {
34
  const springs = useSpring({
35
    scale: [1, 1, 1],
36
    rotation: [0, Math.PI, 0],
37
    from: { scale: [0, 0, 0], rotation: [0, 0, 0] },
38
  });
39

40
  return (
41
    <animated.mesh {...springs}>
42
      <boxGeometry args={[1, 1, 1]} />
43
      <meshStandardMaterial color="orange" />
44
    </animated.mesh>
45
  );
46
}
47

48
function App() {
49
  return (
50
    <Canvas>
51
      <AnimatedCube />
52
    </Canvas>
53
  );
54
}
55
```
56

57
## Architecture
58

59
@react-spring/three is built around several key components:
60

61
- **Animated Components**: Three.js primitives wrapped with spring animation capabilities (`animated.mesh`, `animated.material`, etc.)
62
- **React Spring Core**: Full re-export of all react-spring hooks and components for animations
63
- **Three.js Integration**: Automatic mapping of all Three.js classes to animated components
64
- **R3F Integration**: Seamless integration with React Three Fiber's render loop and prop application system
65

66
## Capabilities
67

68
### Animated Three.js Components
69

70
Animated versions of all Three.js objects and components for use with react-spring animations. Automatically generated from Three.js class names.
71

72
```typescript { .api }
73
const animated: WithAnimated;
74
const a: WithAnimated; // Short alias
75

76
type WithAnimated = {
77
  <T extends ElementType>(wrappedComponent: T): AnimatedComponent<T>;
78
} & AnimatedPrimitives;
79

80
type AnimatedPrimitives = {
81
  [P in Primitives]: AnimatedComponent<FC<JSX.IntrinsicElements[P]>>;
82
};
83
```
84

85
[Animated Components](./animated-components.md)
86

87
### Spring Animation Hooks
88

89
Core react-spring hooks for creating and managing spring-based animations in Three.js scenes.
90

91
```typescript { .api }
92
function useSpring(config: SpringConfig): SpringValues;
93
function useSprings(count: number, configs: SpringConfig[]): SpringValues[];
94
function useSpringRef(): SpringRef;
95
function useSpringValue(initial: any): SpringValue;
96
function useTrail(count: number, config: SpringConfig): SpringValues[];
97
function useTransition<T>(
98
  items: T[],
99
  config: TransitionConfig<T>
100
): TransitionValues<T>[];
101
```
102

103
[Spring Hooks](./spring-hooks.md)
104

105
### Animation Components
106

107
Declarative components for spring animations as an alternative to hooks.
108

109
```typescript { .api }
110
function Spring(props: SpringProps): JSX.Element;
111
function Trail(props: TrailProps): JSX.Element;
112
function Transition<T>(props: TransitionProps<T>): JSX.Element;
113
```
114

115
[Animation Components](./animation-components.md)
116

117
### Advanced Animation Features
118

119
Advanced animation capabilities including chaining, imperative control, and utility hooks.
120

121
```typescript { .api }
122
function useChain(refs: SpringRef[], timeSteps?: number[]): void;
123
function useScroll(config: ScrollConfig): SpringValues;
124
function useResize(config: ResizeConfig): SpringValues;
125
function useInView(config: InViewConfig): [SpringValues, RefCallback];
126
```
127

128
[Advanced Features](./advanced-features.md)
129

130
## Types
131

132
Core type definitions used throughout the animated Three.js ecosystem.
133

134
```typescript { .api }
135
type AnimatedComponent<T extends ElementType> =
136
  ForwardRefExoticComponent<AnimatedProps<ComponentPropsWithRef<T>>>;
137

138
type AnimatedProps<Props extends object> = {
139
  [P in keyof Props]: P extends 'ref' | 'key'
140
    ? Props[P]
141
    : AnimatedProp<Props[P]>;
142
};
143

144
type AnimatedProp<T> = T | SpringValue<T>;
145

146
type Primitives = keyof JSX.IntrinsicElements;
147

148
type AnimatedPrimitives = {
149
  [P in Primitives]: AnimatedComponent<FC<JSX.IntrinsicElements[P]>>;
150
};
151

152
interface SpringConfig {
153
  from?: any;
154
  to?: any;
155
  config?: {
156
    tension?: number;
157
    friction?: number;
158
    mass?: number;
159
    clamp?: boolean;
160
    precision?: number;
161
    velocity?: number;
162
    duration?: number;
163
    easing?: (t: number) => number;
164
  };
165
  loop?: boolean | LoopConfig;
166
  delay?: number;
167
  immediate?: boolean;
168
  reset?: boolean;
169
  reverse?: boolean;
170
  cancel?: boolean;
171
  pause?: boolean;
172
  onStart?: (result: AnimationResult) => void;
173
  onChange?: (result: AnimationResult) => void;
174
  onRest?: (result: AnimationResult) => void;
175
}
176

177
interface SpringValues {
178
  [key: string]: SpringValue;
179
}
180

181
interface SpringRef {
182
  start(): void;
183
  stop(): void;
184
  update(config: Partial<SpringConfig>): void;
185
  set(values: any): void;
186
}
187

188
class SpringValue<T = any> {
189
  get(): T;
190
  set(value: T): void;
191
  start(config?: SpringConfig): Promise<void>;
192
  stop(): void;
193
  to(value: T): SpringValue<T>;
194
}
195

196
interface LoopConfig {
197
  reverse?: boolean;
198
  reset?: boolean;
199
}
200

201
interface AnimationResult {
202
  value: any;
203
  finished: boolean;
204
  cancelled: boolean;
205
}
206
```