0
# Animation Components
1

2
Declarative components for spring animations as an alternative to hooks. These components provide a render-prop pattern for creating animations without using hooks.
3

4
## Capabilities
5

6
### Spring Component
7

8
Declarative component for single spring animations using render props.
9

10
```typescript { .api }
11
/**
12
 * Declarative spring animation component
13
 * @param props - Spring configuration and render function
14
 * @returns JSX element with animated values passed to children
15
 */
16
function Spring(props: SpringProps): JSX.Element;
17

18
interface SpringProps {
19
  from?: any;
20
  to?: any;
21
  config?: SpringConfig["config"];
22
  loop?: boolean | LoopConfig;
23
  delay?: number;
24
  immediate?: boolean;
25
  reset?: boolean;
26
  reverse?: boolean;
27
  cancel?: boolean;
28
  pause?: boolean;
29
  onStart?: (result: AnimationResult) => void;
30
  onChange?: (result: AnimationResult) => void;
31
  onRest?: (result: AnimationResult) => void;
32
  children: (springs: SpringValues) => JSX.Element;
33
}
34
```
35

36
**Usage Examples:**
37

38
```typescript
39
import { Spring, animated } from "@react-spring/three";
40

41
function DeclarativeSpring() {
42
  return (
43
    <Spring
44
      from={{ position: [0, 0, 0], rotation: [0, 0, 0] }}
45
      to={{ position: [0, 2, 0], rotation: [0, Math.PI, 0] }}
46
      config={{ tension: 200, friction: 25 }}
47
    >
48
      {(springs) => (
49
        <animated.mesh {...springs}>
50
          <boxGeometry />
51
          <meshStandardMaterial color="blue" />
52
        </animated.mesh>
53
      )}
54
    </Spring>
55
  );
56
}
57

58
// With dynamic configuration
59
function DynamicSpring({ active }) {
60
  return (
61
    <Spring
62
      to={{
63
        scale: active ? [1.2, 1.2, 1.2] : [1, 1, 1],
64
        color: active ? "#ff6b6b" : "#4ecdc4",
65
      }}
66
      config={{ mass: 1, tension: 280, friction: 60 }}
67
    >
68
      {({ scale, color }) => (
69
        <animated.mesh scale={scale}>
70
          <boxGeometry />
71
          <animated.meshStandardMaterial color={color} />
72
        </animated.mesh>
73
      )}
74
    </Spring>
75
  );
76
}
77
```
78

79
### Trail Component
80

81
Declarative component for trail animations with staggered timing.
82

83
```typescript { .api }
84
/**
85
 * Declarative trail animation component
86
 * @param props - Trail configuration and render function
87
 * @returns JSX element with array of animated values
88
 */
89
function Trail<T>(props: TrailProps<T>): JSX.Element;
90

91
interface TrailProps<T> {
92
  items: T[];
93
  from?: any;
94
  to?: any;
95
  config?: SpringConfig["config"];
96
  delay?: number;
97
  reverse?: boolean;
98
  onStart?: (result: AnimationResult, item: T, index: number) => void;
99
  onChange?: (result: AnimationResult, item: T, index: number) => void;
100
  onRest?: (result: AnimationResult, item: T, index: number) => void;
101
  children: (item: T, index: number, springs: SpringValues) => JSX.Element;
102
}
103
```
104

105
**Usage Examples:**
106

107
```typescript
108
import { Trail, animated } from "@react-spring/three";
109

110
function DeclarativeTrail({ items }) {
111
  return (
112
    <Trail
113
      items={items}
114
      from={{ position: [0, -5, 0], opacity: 0 }}
115
      to={(item, index) => ({
116
        position: [index * 2, 0, 0],
117
        opacity: 1,
118
      })}
119
      config={{ mass: 5, tension: 2000, friction: 200 }}
120
    >
121
      {(item, index, springs) => (
122
        <animated.mesh key={item.id} {...springs}>
123
          <boxGeometry />
124
          <meshStandardMaterial color={item.color} />
125
        </animated.mesh>
126
      )}
127
    </Trail>
128
  );
129
}
130
```
131

132
### Transition Component
133

134
Declarative component for enter/exit transitions of dynamic lists.
135

136
```typescript { .api }
137
/**
138
 * Declarative transition animation component
139
 * @param props - Transition configuration and render function
140
 * @returns JSX element with transition animations
141
 */
142
function Transition<T>(props: TransitionProps<T>): JSX.Element;
143

144
interface TransitionProps<T> {
145
  items: T[];
146
  keys?: (item: T) => any;
147
  from?: any;
148
  enter?: any;
149
  update?: any;
150
  leave?: any;
151
  trail?: number;
152
  expires?: boolean | number;
153
  config?: SpringConfig["config"];
154
  onStart?: (result: AnimationResult, item: T, key: any) => void;
155
  onChange?: (result: AnimationResult, item: T, key: any) => void;
156
  onRest?: (result: AnimationResult, item: T, key: any) => void;
157
  children: (item: T, springs: SpringValues, key: any) => JSX.Element;
158
}
159
```
160

161
**Usage Examples:**
162

163
```typescript
164
import { Transition, animated } from "@react-spring/three";
165

166
function DeclarativeTransition({ items }) {
167
  return (
168
    <Transition
169
      items={items}
170
      keys={(item) => item.id}
171
      from={{ position: [0, -2, 0], opacity: 0, scale: [0, 0, 0] }}
172
      enter={{ position: [0, 0, 0], opacity: 1, scale: [1, 1, 1] }}
173
      leave={{ position: [0, 2, 0], opacity: 0, scale: [0, 0, 0] }}
174
      config={{ tension: 200, friction: 25 }}
175
    >
176
      {(item, springs, key) => (
177
        <animated.mesh key={key} {...springs}>
178
          <boxGeometry />
179
          <meshStandardMaterial color={item.color} />
180
        </animated.mesh>
181
      )}
182
    </Transition>
183
  );
184
}
185

186
// Complex transition with update phase
187
function ComplexTransition({ items }) {
188
  return (
189
    <Transition
190
      items={items}
191
      keys={(item) => item.id}
192
      from={{ position: [0, -5, 0], opacity: 0 }}
193
      enter={(item) => ({ position: item.position, opacity: 1 })}
194
      update={(item) => ({ position: item.position })}
195
      leave={{ position: [0, 5, 0], opacity: 0 }}
196
      trail={100}
197
      expires={5000}
198
    >
199
      {(item, springs, key) => (
200
        <animated.mesh key={key} {...springs}>
201
          <sphereGeometry args={[item.radius]} />
202
          <meshStandardMaterial color={item.color} />
203
        </animated.mesh>
204
      )}
205
    </Transition>
206
  );
207
}
208
```
209

210
## Component vs Hook Patterns
211

212
Animation components and hooks serve different use cases:
213

214
**Use Components when:**
215
- You prefer declarative, JSX-based animations
216
- Working with render props patterns
217
- Need to pass animation logic down through props
218
- Building reusable animation templates
219

220
**Use Hooks when:**
221
- You need imperative control over animations
222
- Working with complex state logic
223
- Need to share animated values between components
224
- Building custom animation hooks
225

226
**Mixed Usage:**
227

228
```typescript
229
import { Spring, animated, useSpringRef } from "@react-spring/three";
230

231
function MixedApproach() {
232
  const ref = useSpringRef();
233

234
  const handleClick = () => {
235
    ref.start({ to: { rotation: [0, Math.PI * 2, 0] } });
236
  };
237

238
  return (
239
    <Spring
240
      ref={ref}
241
      from={{ position: [0, 0, 0] }}
242
      to={{ position: [0, 1, 0] }}
243
    >
244
      {(springs) => (
245
        <animated.mesh {...springs} onClick={handleClick}>
246
          <boxGeometry />
247
          <meshStandardMaterial />
248
        </animated.mesh>
249
      )}
250
    </Spring>
251
  );
252
}
253
```
254

255
## Types
256

257
```typescript { .api }
258
interface SpringProps {
259
  from?: any;
260
  to?: any;
261
  config?: SpringConfig["config"];
262
  loop?: boolean | LoopConfig;
263
  delay?: number;
264
  immediate?: boolean;
265
  reset?: boolean;
266
  reverse?: boolean;
267
  cancel?: boolean;
268
  pause?: boolean;
269
  ref?: SpringRef;
270
  onStart?: (result: AnimationResult) => void;
271
  onChange?: (result: AnimationResult) => void;
272
  onRest?: (result: AnimationResult) => void;
273
  children: (springs: SpringValues) => JSX.Element;
274
}
275

276
interface TrailProps<T> {
277
  items: T[];
278
  from?: any;
279
  to?: any | ((item: T, index: number) => any);
280
  config?: SpringConfig["config"];
281
  delay?: number;
282
  reverse?: boolean;
283
  ref?: SpringRef;
284
  onStart?: (result: AnimationResult, item: T, index: number) => void;
285
  onChange?: (result: AnimationResult, item: T, index: number) => void;
286
  onRest?: (result: AnimationResult, item: T, index: number) => void;
287
  children: (item: T, index: number, springs: SpringValues) => JSX.Element;
288
}
289

290
interface TransitionProps<T> {
291
  items: T[];
292
  keys?: (item: T) => any;
293
  from?: any;
294
  enter?: any | ((item: T) => any);
295
  update?: any | ((item: T) => any);
296
  leave?: any | ((item: T) => any);
297
  trail?: number;
298
  expires?: boolean | number;
299
  config?: SpringConfig["config"];
300
  ref?: SpringRef;
301
  onStart?: (result: AnimationResult, item: T, key: any) => void;
302
  onChange?: (result: AnimationResult, item: T, key: any) => void;
303
  onRest?: (result: AnimationResult, item: T, key: any) => void;
304
  children: (item: T, springs: SpringValues, key: any) => JSX.Element;
305
}
306
```