0
# Spring Animation Hooks
1

2
Core react-spring hooks for creating and managing spring-based animations in Three.js scenes. These hooks provide the foundation for all spring animations in @react-spring/three.
3

4
## Capabilities
5

6
### useSpring Hook
7

8
Creates a single spring animation that can animate multiple properties simultaneously.
9

10
```typescript { .api }
11
/**
12
 * Creates a single spring animation
13
 * @param config - Spring configuration with from/to values and options  
14
 * @returns Object with animated values for each configured property
15
 */
16
function useSpring(config: SpringConfig): SpringValues;
17
function useSpring(config: () => SpringConfig): SpringValues;
18
function useSpring(from: any, to: any): SpringValues;
19
```
20

21
**Usage Examples:**
22

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

26
// Basic spring animation
27
function BasicSpring() {
28
  const springs = useSpring({
29
    position: [0, 1, 0],
30
    rotation: [0, Math.PI, 0],
31
    from: { position: [0, 0, 0], rotation: [0, 0, 0] },
32
    config: { tension: 200, friction: 25 },
33
  });
34

35
  return (
36
    <animated.mesh {...springs}>
37
      <boxGeometry />
38
      <meshStandardMaterial />
39
    </animated.mesh>
40
  );
41
}
42

43
// Functional config for dynamic values
44
function DynamicSpring({ active }) {
45
  const springs = useSpring(() => ({
46
    scale: active ? [1.2, 1.2, 1.2] : [1, 1, 1],
47
    color: active ? "#ff6b6b" : "#4ecdc4",
48
  }));
49

50
  return (
51
    <animated.mesh scale={springs.scale}>
52
      <boxGeometry />
53
      <animated.meshStandardMaterial color={springs.color} />
54
    </animated.mesh>
55
  );
56
}
57
```
58

59
### useSprings Hook
60

61
Creates multiple spring animations, useful for animating lists of objects.
62

63
```typescript { .api }
64
/**
65
 * Creates multiple spring animations
66
 * @param count - Number of springs to create
67
 * @param configs - Array of configurations or function returning configs
68
 * @returns Array of spring value objects
69
 */
70
function useSprings(count: number, configs: SpringConfig[]): SpringValues[];
71
function useSprings(count: number, configFn: (index: number) => SpringConfig): SpringValues[];
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
import { animated, useSprings } from "@react-spring/three";
78

79
function SpringsList({ items }) {
80
  const springs = useSprings(
81
    items.length,
82
    items.map((item, index) => ({
83
      position: [index * 2, 0, 0],
84
      rotation: [0, item.rotation, 0],
85
      from: { position: [0, -10, 0], rotation: [0, 0, 0] },
86
      delay: index * 100,
87
    }))
88
  );
89

90
  return (
91
    <>
92
      {springs.map((spring, index) => (
93
        <animated.mesh key={index} {...spring}>
94
          <boxGeometry />
95
          <meshStandardMaterial color={items[index].color} />
96
        </animated.mesh>
97
      ))}
98
    </>
99
  );
100
}
101
```
102

103
### useSpringValue Hook
104

105
Creates a single animated value that can be used independently.
106

107
```typescript { .api }
108
/**
109
 * Creates a single animated value
110
 * @param initial - Initial value
111
 * @returns SpringValue instance with control methods
112
 */
113
function useSpringValue(initial: any): SpringValue;
114
```
115

116
**Usage Examples:**
117

118
```typescript
119
import { animated, useSpringValue } from "@react-spring/three";
120
import { useEffect } from "react";
121

122
function SingleValueSpring() {
123
  const opacity = useSpringValue(0);
124

125
  useEffect(() => {
126
    opacity.start({ to: 1, config: { duration: 1000 } });
127
  }, []);
128

129
  return (
130
    <mesh>
131
      <boxGeometry />
132
      <animated.meshStandardMaterial transparent opacity={opacity} />
133
    </mesh>
134
  );
135
}
136
```
137

138
### useSpringRef Hook
139

140
Creates a reference for imperative control over springs.
141

142
```typescript { .api }
143
/**
144
 * Creates a spring reference for imperative control
145
 * @returns SpringRef with control methods
146
 */
147
function useSpringRef(): SpringRef;
148
```
149

150
**Usage Examples:**
151

152
```typescript
153
import { animated, useSpring, useSpringRef } from "@react-spring/three";
154

155
function ImperativeSpring() {
156
  const ref = useSpringRef();
157
  const springs = useSpring({
158
    ref,
159
    position: [0, 0, 0],
160
    from: { position: [0, -5, 0] },
161
    config: { tension: 280, friction: 60 },
162
  });
163

164
  const handleClick = () => {
165
    ref.start({ position: [Math.random() * 4 - 2, Math.random() * 4 - 2, 0] });
166
  };
167

168
  return (
169
    <animated.mesh {...springs} onClick={handleClick}>
170
      <boxGeometry />
171
      <meshStandardMaterial />
172
    </animated.mesh>
173
  );
174
}
175
```
176

177
### useTrail Hook
178

179
Creates a trail of springs that follow each other with a stagger effect.
180

181
```typescript { .api }
182
/**
183
 * Creates a trail of staggered springs
184
 * @param count - Number of items in trail
185
 * @param config - Spring configuration applied to all items
186
 * @returns Array of spring values with staggered timing
187
 */
188
function useTrail(count: number, config: SpringConfig): SpringValues[];
189
function useTrail(count: number, configFn: (index: number) => SpringConfig): SpringValues[];
190
```
191

192
**Usage Examples:**
193

194
```typescript
195
import { animated, useTrail } from "@react-spring/three";
196

197
function TrailAnimation({ items }) {
198
  const trail = useTrail(items.length, {
199
    position: items.map((_, i) => [i * 2, 0, 0]),
200
    opacity: 1,
201
    from: { position: [0, -10, 0], opacity: 0 },
202
    config: { mass: 5, tension: 2000, friction: 200 },
203
  });
204

205
  return (
206
    <>
207
      {trail.map((springs, index) => (
208
        <animated.mesh key={index} {...springs}>
209
          <sphereGeometry args={[0.5]} />
210
          <animated.meshStandardMaterial transparent />
211
        </animated.mesh>
212
      ))}
213
    </>
214
  );
215
}
216
```
217

218
### useTransition Hook
219

220
Creates enter/exit animations for dynamic lists of objects.
221

222
```typescript { .api }
223
/**
224
 * Creates enter/exit transitions for dynamic lists
225
 * @param items - Array of items to transition
226
 * @param config - Transition configuration with enter/leave/update
227
 * @returns Array of transition render props
228
 */
229
function useTransition<T>(
230
  items: T[],
231
  config: TransitionConfig<T>
232
): TransitionValues<T>[];
233

234
interface TransitionConfig<T> {
235
  from?: any;
236
  enter?: any;
237
  update?: any;
238
  leave?: any;
239
  keys?: (item: T) => any;
240
  trail?: number;
241
  expires?: boolean | number;
242
  config?: SpringConfig["config"];
243
}
244

245
interface TransitionValues<T> {
246
  item: T;
247
  key: any;
248
  props: SpringValues;
249
}
250
```
251

252
**Usage Examples:**
253

254
```typescript
255
import { animated, useTransition } from "@react-spring/three";
256

257
function TransitionList({ items }) {
258
  const transitions = useTransition(items, {
259
    from: { position: [0, -2, 0], opacity: 0, scale: [0, 0, 0] },
260
    enter: { position: [0, 0, 0], opacity: 1, scale: [1, 1, 1] },
261
    leave: { position: [0, 2, 0], opacity: 0, scale: [0, 0, 0] },
262
    keys: (item) => item.id,
263
  });
264

265
  return (
266
    <>
267
      {transitions.map(({ item, key, props }) => (
268
        <animated.mesh key={key} {...props}>
269
          <boxGeometry />
270
          <meshStandardMaterial color={item.color} />
271
        </animated.mesh>
272
      ))}
273
    </>
274
  );
275
}
276
```
277

278
## Types
279

280
```typescript { .api }
281
interface SpringConfig {
282
  from?: any;
283
  to?: any;
284
  config?: {
285
    tension?: number;
286
    friction?: number;
287
    mass?: number;
288
    clamp?: boolean;
289
    precision?: number;
290
    velocity?: number;
291
    duration?: number;
292
    easing?: (t: number) => number;
293
  };
294
  loop?: boolean | LoopConfig;
295
  delay?: number;
296
  immediate?: boolean;
297
  reset?: boolean;
298
  reverse?: boolean;
299
  cancel?: boolean;
300
  pause?: boolean;
301
  onStart?: (result: AnimationResult) => void;
302
  onChange?: (result: AnimationResult) => void;
303
  onRest?: (result: AnimationResult) => void;
304
}
305

306
interface SpringValues {
307
  [key: string]: SpringValue;
308
}
309

310
interface SpringRef {
311
  start(config?: Partial<SpringConfig>): Promise<void>;
312
  stop(): void;
313
  update(config: Partial<SpringConfig>): void;
314
  set(values: any): void;
315
}
316

317
class SpringValue {
318
  get(): any;
319
  set(value: any): void;
320
  start(config?: SpringConfig): Promise<void>;
321
  stop(): void;
322
  to(value: any): Promise<void>;
323
}
324

325
interface LoopConfig {
326
  reverse?: boolean;
327
  reset?: boolean;
328
}
329

330
interface AnimationResult {
331
  value: any;
332
  finished: boolean;
333
  cancelled: boolean;
334
}
335
```