0
# Core Animation
1

2
The core animation system provides a unified interface for creating different types of animations with comprehensive playback controls and lifecycle management.
3

4
## Capabilities
5

6
### Animate Function
7

8
The primary animation function that detects animation type from options and provides unified control interface.
9

10
```typescript { .api }
11
/**
12
 * Creates an animation from the provided options
13
 * @param options - Animation configuration including type, timing, and callbacks
14
 * @returns PlaybackControls interface for stopping the animation
15
 */
16
function animate<V = number>(options: AnimationOptions<V>): PlaybackControls;
17

18
interface PlaybackControls {
19
  /** Stop the animation immediately */
20
  stop: () => void;
21
}
22

23
type AnimationOptions<V> = PlaybackOptions<V> & 
24
  (DecayOptions | KeyframeOptions<V> | SpringOptions);
25

26
interface PlaybackOptions<V> {
27
  /** Whether to start animation immediately (default: true) */
28
  autoplay?: boolean;
29
  /** Custom driver for animation timing (default: framesync) */
30
  driver?: Driver;
31
  /** Starting elapsed time in milliseconds */
32
  elapsed?: number;
33
  /** Starting value for animation */
34
  from?: V;
35
  /** Number of times to repeat animation (0 = no repeat) */
36
  repeat?: number;
37
  /** How to handle repeats: loop, reverse, or mirror */
38
  repeatType?: "loop" | "reverse" | "mirror";
39
  /** Delay between repeats in milliseconds */
40
  repeatDelay?: number;
41
  /** Animation type hint (auto-detected if not provided) */
42
  type?: "spring" | "decay" | "keyframes";
43
  /** Called with latest value on each frame */
44
  onUpdate?: (latest: V) => void;
45
  /** Called when animation starts playing */
46
  onPlay?: () => void;
47
  /** Called when animation completes (not on stop) */
48
  onComplete?: () => void;
49
  /** Called each time animation repeats */
50
  onRepeat?: () => void;
51
  /** Called when animation is stopped */
52
  onStop?: () => void;
53
}
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
import { animate } from "popmotion";
60

61
// Basic keyframe animation
62
animate({
63
  from: 0,
64
  to: 100,
65
  duration: 1000,
66
  onUpdate: (value) => element.style.opacity = value / 100
67
});
68

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

79
// Repeating animation with callbacks
80
const controls = animate({
81
  from: 0,
82
  to: 360,
83
  duration: 2000,
84
  repeat: Infinity,
85
  repeatType: "loop",
86
  onUpdate: (degrees) => element.style.transform = `rotate(${degrees}deg)`,
87
  onComplete: () => console.log("Animation complete"),
88
  onRepeat: () => console.log("Animation repeating")
89
});
90

91
// Stop animation later
92
setTimeout(() => controls.stop(), 5000);
93
```
94

95
### Driver System
96

97
The driver system allows custom timing mechanisms for animations, with framesync as the default.
98

99
```typescript { .api }
100
/**
101
 * Animation driver interface for custom timing control
102
 * @param update - Function to call with elapsed time
103
 * @returns Controls for starting and stopping the driver
104
 */
105
type Driver = (update: (timestamp: number) => void) => DriverControls;
106

107
interface DriverControls {
108
  /** Start the driver timing loop */
109
  start: () => void;
110
  /** Stop the driver timing loop */
111
  stop: () => void;
112
}
113
```
114

115
**Usage Examples:**
116

117
```typescript
118
import { animate } from "popmotion";
119

120
// Custom driver using setInterval
121
const intervalDriver = (update) => {
122
  let intervalId;
123
  let startTime = Date.now();
124
  
125
  return {
126
    start: () => {
127
      intervalId = setInterval(() => {
128
        update(Date.now() - startTime);
129
      }, 16); // ~60fps
130
    },
131
    stop: () => clearInterval(intervalId)
132
  };
133
};
134

135
animate({
136
  from: 0,
137
  to: 100,
138
  duration: 1000,
139
  driver: intervalDriver,
140
  onUpdate: (value) => console.log(value)
141
});
142
```
143

144
### Animation State
145

146
The animation state interface defines the structure returned by animation generators.
147

148
```typescript { .api }
149
interface Animation<V> {
150
  /** 
151
   * Get the next animation state for given elapsed time
152
   * @param t - Elapsed time in milliseconds
153
   * @returns Current value and completion status
154
   */
155
  next: (t: number) => AnimationState<V>;
156
  /** Flip the target for mirror-type animations */
157
  flipTarget: () => void;
158
}
159

160
interface AnimationState<V> {
161
  /** Current animated value */
162
  value: V;
163
  /** Whether animation has completed */
164
  done: boolean;
165
}
166
```
167

168
## Repeat Modes
169

170
### Loop Mode
171
Restarts animation from beginning on each repeat.
172

173
```typescript
174
animate({
175
  from: 0,
176
  to: 100,
177
  duration: 1000,
178
  repeat: 3,
179
  repeatType: "loop" // 0→100, 0→100, 0→100, 0→100
180
});
181
```
182

183
### Reverse Mode  
184
Alternates direction on each repeat.
185

186
```typescript
187
animate({
188
  from: 0,
189
  to: 100,
190
  duration: 1000,
191
  repeat: 3,
192
  repeatType: "reverse" // 0→100, 100→0, 0→100, 100→0
193
});
194
```
195

196
### Mirror Mode
197
Flips the target value on each repeat while maintaining direction.
198

199
```typescript
200
animate({
201
  from: 0,
202
  to: 100,
203
  duration: 1000,
204
  repeat: 3,
205
  repeatType: "mirror" // 0→100, 100→0, 0→100, 100→0
206
});
207
```