0
# Animation Generators
1

2
Animation generators are specialized functions that create different types of motion patterns with precise control over physics parameters and timing. They return Animation objects that can be used directly or with the core animate function.
3

4
## Capabilities
5

6
### Spring Animation Generator
7

8
Creates physics-based spring animations with natural motion characteristics.
9

10
```typescript { .api }
11
/**
12
 * Creates a spring animation generator
13
 * @param options - Spring configuration including physics parameters
14
 * @returns Animation generator for spring motion
15
 */
16
function spring(options: SpringOptions): Animation<number>;
17

18
interface SpringOptions extends PhysicsSpringOptions {
19
  /** Starting value */
20
  from?: number;
21
  /** Target value */
22
  to?: number;
23
  /** Duration in milliseconds (alternative to physics params) */
24
  duration?: number;
25
  /** Bounce factor (0-1, alternative to damping) */
26
  bounce?: number;
27
  /** Speed threshold for completion detection */
28
  restSpeed?: number;
29
  /** Distance threshold for completion detection */
30
  restDelta?: number;
31
}
32

33
interface PhysicsSpringOptions {
34
  /** Initial velocity */
35
  velocity?: number;
36
  /** Spring stiffness (higher = stiffer) */
37
  stiffness?: number;
38
  /** Spring damping (higher = less oscillation) */
39
  damping?: number;
40
  /** Mass of the animated object */
41
  mass?: number;
42
}
43
```
44

45
**Usage Examples:**
46

47
```typescript
48
import { spring, animate } from "popmotion";
49

50
// Direct spring generator usage
51
const springGen = spring({
52
  from: 0,
53
  to: 100,
54
  stiffness: 400,
55
  damping: 40
56
});
57

58
// Manual stepping
59
let time = 0;
60
const step = () => {
61
  const { value, done } = springGen.next(time);
62
  console.log(value);
63
  time += 16;
64
  if (!done) requestAnimationFrame(step);
65
};
66
step();
67

68
// With animate function (recommended)
69
animate({
70
  from: 0,
71
  to: 100,
72
  type: "spring",
73
  stiffness: 400,
74
  damping: 40,
75
  onUpdate: (value) => element.style.left = value + "px"
76
});
77

78
// Duration-based spring (easier tuning)
79
animate({
80
  from: 0,
81
  to: 100,
82
  type: "spring",
83
  duration: 800,
84
  bounce: 0.25
85
});
86
```
87

88
### Decay Animation Generator
89

90
Creates exponential decay animations typically used for momentum scrolling and drag interactions.
91

92
```typescript { .api }
93
/**
94
 * Creates a decay animation generator
95
 * @param options - Decay configuration including velocity and physics
96
 * @returns Animation generator for decay motion
97
 */
98
function decay(options: DecayOptions): Animation<number>;
99

100
interface DecayOptions {
101
  /** Starting value */
102
  from?: number;
103
  /** Target value (optional, not used in decay calculation) */
104
  to?: number;
105
  /** Initial velocity */
106
  velocity?: number;
107
  /** Decay power factor (default: 0.8) */
108
  power?: number;
109
  /** Time constant for decay rate */
110
  timeConstant?: number;
111
  /** Function to modify calculated target */
112
  modifyTarget?: (target: number) => number;
113
  /** Distance threshold for completion */
114
  restDelta?: number;
115
}
116
```
117

118
**Usage Examples:**
119

120
```typescript
121
import { decay, animate } from "popmotion";
122

123
// Momentum scrolling effect
124
let scrollY = 0;
125
animate({
126
  from: scrollY,
127
  velocity: -500, // Initial upward velocity
128
  type: "decay",
129
  power: 0.8,
130
  timeConstant: 325,
131
  onUpdate: (value) => {
132
    scrollY = value;
133
    element.scrollTop = Math.max(0, value);
134
  }
135
});
136

137
// Drag release with boundaries
138
animate({
139
  from: currentX,
140
  velocity: dragVelocity,
141
  type: "decay",
142
  modifyTarget: (target) => Math.max(0, Math.min(maxX, target)),
143
  onUpdate: (x) => element.style.transform = `translateX(${x}px)`
144
});
145

146
// Custom decay with direct generator
147
const decayGen = decay({
148
  from: 100,
149
  velocity: -200,
150
  power: 0.9
151
});
152
```
153

154
### Keyframes Animation Generator
155

156
Creates keyframe-based animations with support for multiple values, custom easing per segment, and time offsets.
157

158
```typescript { .api }
159
/**
160
 * Creates a keyframe animation generator
161
 * @param options - Keyframe configuration including values and timing
162
 * @returns Animation generator for keyframe motion
163
 */
164
function keyframes<V = number>(options: KeyframeOptions<V>): Animation<V>;
165

166
interface KeyframeOptions<V = number> {
167
  /** Target values (array creates keyframes, single value creates simple tween) */
168
  to: V | V[];
169
  /** Starting value */
170
  from?: V;
171
  /** Total duration in milliseconds */
172
  duration?: number;
173
  /** Easing function(s) - single for all segments or array per segment */
174
  ease?: Easing | Easing[];
175
  /** Time offsets for each keyframe (0-1, length must match values) */
176
  offset?: number[];
177
}
178
```
179

180
**Usage Examples:**
181

182
```typescript
183
import { keyframes, animate } from "popmotion";
184

185
// Simple keyframes
186
animate({
187
  from: 0,
188
  to: [25, 50, 75, 100],
189
  duration: 2000,
190
  onUpdate: (value) => element.style.left = value + "px"
191
});
192

193
// Complex keyframes with different easing per segment
194
animate({
195
  from: 0,
196
  to: [50, 100, 0],
197
  duration: 3000,
198
  ease: ["easeOut", "linear", "easeIn"],
199
  onUpdate: (value) => element.style.opacity = value / 100
200
});
201

202
// Custom timing with offsets
203
animate({
204
  from: 0,
205
  to: [20, 80, 100],
206
  duration: 2000,
207
  offset: [0, 0.1, 1], // 20% at 10% through, 80% at 100%
208
  ease: "easeInOut",
209
  onUpdate: (value) => element.style.transform = `scale(${value / 100})`
210
});
211

212
// Color keyframes
213
animate({
214
  from: "#ff0000",
215
  to: ["#00ff00", "#0000ff", "#ff0000"],
216
  duration: 3000,
217
  onUpdate: (color) => element.style.backgroundColor = color
218
});
219
```
220

221
## Animation Object Interface
222

223
All generators return Animation objects with a consistent interface:
224

225
```typescript { .api }
226
interface Animation<V> {
227
  /**
228
   * Calculate animation state at given time
229
   * @param t - Elapsed time in milliseconds
230
   * @returns Current value and completion status
231
   */
232
  next: (t: number) => {
233
    value: V;
234
    done: boolean;
235
  };
236
  
237
  /** Flip target for mirror-type repeat animations */
238
  flipTarget: () => void;
239
}
240
```
241

242
## Physics Parameter Guidelines
243

244
### Spring Parameters
245

246
- **Stiffness**: 100-1000 (higher = faster, snappier)
247
- **Damping**: 10-100 (higher = less bounce)
248
- **Mass**: 0.1-10 (higher = slower, more momentum)
249
- **Duration**: 300-2000ms (alternative to physics params)
250
- **Bounce**: 0-1 (0 = no bounce, 1 = maximum bounce)
251

252
### Decay Parameters
253

254
- **Power**: 0.6-0.9 (higher = slower decay)
255
- **TimeConstant**: 100-500ms (higher = longer decay)
256
- **Velocity**: Depends on interaction (pixels/second)
257

258
### Keyframe Parameters
259

260
- **Duration**: 500-5000ms typical range
261
- **Offset**: Must sum to 1.0 if provided
262
- **Ease**: Can be different for each segment