0
# Animation Controls
1

2
Imperative animation controls for complex sequences, timeline management, and dynamic animation orchestration.
3

4
## Capabilities
5

6
### Animation Controls Object
7

8
Provides imperative control over animations with methods for starting, stopping, and managing animation sequences.
9

10
```typescript { .api }
11
/**
12
 * Hook for creating animation controls
13
 * @returns Animation controls object
14
 */
15
function useAnimationControls(): AnimationControls;
16

17
interface AnimationControls {
18
  /** Start animation with target values or variant labels */
19
  start(definition: Target | VariantLabels): Promise<void>;
20
  /** Stop all running animations */
21
  stop(): void;
22
  /** Set values immediately without animation */
23
  set(definition: Target): void;
24
  /** Mount controls to component lifecycle */
25
  mount(): void;
26
  /** Unmount controls from component lifecycle */
27
  unmount(): void;
28
  /** Get current animation state */
29
  getState(): AnimationState;
30
}
31

32
interface AnimationState {
33
  /** Currently animating properties */
34
  animating: string[];
35
  /** Current target values */
36
  target: Target;
37
  /** Animation progress (0-1) */
38
  progress: number;
39
}
40

41
type Target = {
42
  [property: string]: string | number | MotionValue;
43
};
44

45
type VariantLabels = string | string[];
46
```
47

48
**Usage Examples:**
49

50
```typescript
51
import { motion, useAnimationControls } from "motion/react";
52
import { useEffect } from "react";
53

54
function ControlledAnimation() {
55
  const controls = useAnimationControls();
56

57
  useEffect(() => {
58
    // Start animation sequence
59
    const sequence = async () => {
60
      await controls.start({ scale: 1.2, transition: { duration: 0.5 } });
61
      await controls.start({ rotate: 180, transition: { duration: 0.5 } });
62
      await controls.start({ scale: 1, rotate: 0, transition: { duration: 0.5 } });
63
    };
64
    
65
    sequence();
66
  }, [controls]);
67

68
  return (
69
    <motion.div
70
      animate={controls}
71
      style={{
72
        width: 100,
73
        height: 100,
74
        background: "#6366f1",
75
        borderRadius: 8
76
      }}
77
    />
78
  );
79
}
80
```
81

82
### Animation Sequencing
83

84
Tools for creating complex animation sequences with precise timing control.
85

86
```typescript { .api }
87
/**
88
 * Create animation sequence with timing control
89
 * @param animations - Array of animation steps
90
 * @returns Promise that resolves when sequence completes
91
 */
92
function animateSequence(animations: AnimationStep[]): Promise<void>;
93

94
interface AnimationStep {
95
  /** Animation controls or target element */
96
  target: AnimationControls | string | Element;
97
  /** Animation values */
98
  keyframes: Target;
99
  /** Animation options */
100
  options?: AnimationOptions;
101
  /** When to start relative to sequence (in seconds) */
102
  at?: number | string;
103
}
104
```
105

106
**Usage Examples:**
107

108
```typescript
109
import { useAnimationControls, animateSequence } from "motion/react";
110

111
function ComplexSequence() {
112
  const titleControls = useAnimationControls();
113
  const subtitleControls = useAnimationControls();
114
  const buttonControls = useAnimationControls();
115

116
  const playSequence = async () => {
117
    await animateSequence([
118
      {
119
        target: titleControls,
120
        keyframes: { opacity: 1, y: 0 },
121
        options: { duration: 0.6 }
122
      },
123
      {
124
        target: subtitleControls,
125
        keyframes: { opacity: 1, y: 0 },
126
        options: { duration: 0.6 },
127
        at: 0.2 // Start 0.2s after previous animation
128
      },
129
      {
130
        target: buttonControls,
131
        keyframes: { opacity: 1, scale: 1 },
132
        options: { duration: 0.4 },
133
        at: 0.4
134
      }
135
    ]);
136
  };
137

138
  return (
139
    <div>
140
      <motion.h1
141
        animate={titleControls}
142
        initial={{ opacity: 0, y: 20 }}
143
      >
144
        Title
145
      </motion.h1>
146
      <motion.p
147
        animate={subtitleControls}
148
        initial={{ opacity: 0, y: 20 }}
149
      >
150
        Subtitle
151
      </motion.p>
152
      <motion.button
153
        animate={buttonControls}
154
        initial={{ opacity: 0, scale: 0.8 }}
155
        onClick={playSequence}
156
      >
157
        Play Sequence
158
      </motion.button>
159
    </div>
160
  );
161
}
162
```
163

164
### Timeline Controls
165

166
Advanced timeline control for managing multiple animations with precise timing.
167

168
```typescript { .api }
169
/**
170
 * Create animation timeline
171
 * @param options - Timeline configuration
172
 * @returns Timeline controls object
173
 */
174
function useTimeline(options?: TimelineOptions): TimelineControls;
175

176
interface TimelineControls {
177
  /** Play timeline from current position */
178
  play(): void;
179
  /** Pause timeline */
180
  pause(): void;
181
  /** Stop timeline and reset to start */
182
  stop(): void;
183
  /** Seek to specific time */
184
  seek(time: number): void;
185
  /** Reverse timeline playback */
186
  reverse(): void;
187
  /** Current playback time */
188
  currentTime: number;
189
  /** Total timeline duration */
190
  duration: number;
191
  /** Playback rate multiplier */
192
  playbackRate: number;
193
  /** Add animation to timeline */
194
  add(animation: TimelineAnimation, time?: number): void;
195
  /** Remove animation from timeline */
196
  remove(animation: TimelineAnimation): void;
197
}
198

199
interface TimelineOptions {
200
  /** Auto-play timeline on creation */
201
  autoplay?: boolean;
202
  /** Loop timeline */
203
  loop?: boolean;
204
  /** Timeline playback rate */
205
  playbackRate?: number;
206
}
207

208
interface TimelineAnimation {
209
  /** Target for animation */
210
  target: AnimationControls | string | Element;
211
  /** Animation keyframes */
212
  keyframes: Target;
213
  /** Animation duration */
214
  duration: number;
215
  /** Start time in timeline */
216
  startTime: number;
217
  /** Animation easing */
218
  ease?: Easing;
219
}
220
```
221

222
### State Machine Integration
223

224
Integration with state machines for complex animation orchestration.
225

226
```typescript { .api }
227
/**
228
 * Create animation state machine
229
 * @param states - State configuration
230
 * @param initialState - Initial state name
231
 * @returns State machine controls
232
 */
233
function useAnimationStateMachine(
234
  states: AnimationStates,
235
  initialState: string
236
): StateMachineControls;
237

238
interface AnimationStates {
239
  [stateName: string]: {
240
    /** Animation values for this state */
241
    animation: Target;
242
    /** Transition configuration */
243
    transition?: Transition;
244
    /** Valid transitions from this state */
245
    transitions?: {
246
      [eventName: string]: string;
247
    };
248
    /** Actions to run on state entry */
249
    onEntry?: () => void;
250
    /** Actions to run on state exit */
251
    onExit?: () => void;
252
  };
253
}
254

255
interface StateMachineControls {
256
  /** Current state name */
257
  currentState: string;
258
  /** Send event to trigger transition */
259
  send(event: string): void;
260
  /** Get all possible events from current state */
261
  getPossibleEvents(): string[];
262
  /** Check if transition is possible */
263
  canTransition(event: string): boolean;
264
}
265
```
266

267
**Usage Examples:**
268

269
```typescript
270
import { motion, useAnimationStateMachine } from "motion/react";
271

272
function StateMachineExample() {
273
  const stateMachine = useAnimationStateMachine({
274
    idle: {
275
      animation: { scale: 1, rotate: 0 },
276
      transitions: {
277
        hover: "hovered",
278
        click: "clicked"
279
      }
280
    },
281
    hovered: {
282
      animation: { scale: 1.1, rotate: 0 },
283
      transitions: {
284
        leave: "idle",
285
        click: "clicked"
286
      }
287
    },
288
    clicked: {
289
      animation: { scale: 0.95, rotate: 360 },
290
      transition: { duration: 0.3 },
291
      transitions: {
292
        release: "idle"
293
      }
294
    }
295
  }, "idle");
296

297
  return (
298
    <motion.div
299
      animate={stateMachine.currentState}
300
      variants={{
301
        idle: { scale: 1, rotate: 0 },
302
        hovered: { scale: 1.1, rotate: 0 },
303
        clicked: { scale: 0.95, rotate: 360 }
304
      }}
305
      onMouseEnter={() => stateMachine.send("hover")}
306
      onMouseLeave={() => stateMachine.send("leave")}
307
      onMouseDown={() => stateMachine.send("click")}
308
      onMouseUp={() => stateMachine.send("release")}
309
      style={{
310
        width: 100,
311
        height: 100,
312
        background: "#f59e0b",
313
        borderRadius: 8,
314
        cursor: "pointer"
315
      }}
316
    >
317
      State: {stateMachine.currentState}
318
    </motion.div>
319
  );
320
}
321
```
322

323
### Animation Composition
324

325
Tools for composing multiple animations together with different combination modes.
326

327
```typescript { .api }
328
/**
329
 * Compose multiple animations
330
 * @param animations - Array of animation controls
331
 * @param mode - Composition mode
332
 * @returns Composed animation controls
333
 */
334
function composeAnimations(
335
  animations: AnimationControls[],
336
  mode: CompositionMode
337
): AnimationControls;
338

339
type CompositionMode = 
340
  | "sequential" // Run animations one after another
341
  | "parallel"   // Run animations simultaneously
342
  | "staggered"  // Run animations with stagger delay
343
  | "alternating"; // Alternate between animations
344

345
interface StaggerOptions {
346
  /** Delay between each animation */
347
  stagger: number;
348
  /** Stagger direction */
349
  from?: "first" | "last" | "center" | number;
350
  /** Ease stagger timing */
351
  ease?: Easing;
352
}
353
```
354

355
### Dynamic Animation Creation
356

357
Runtime creation and modification of animations based on data or user input.
358

359
```typescript { .api }
360
/**
361
 * Create dynamic animation from configuration
362
 * @param config - Animation configuration
363
 * @returns Animation controls
364
 */
365
function createDynamicAnimation(config: DynamicAnimationConfig): AnimationControls;
366

367
interface DynamicAnimationConfig {
368
  /** Target element or controls */
369
  target: string | Element | AnimationControls;
370
  /** Animation properties generator */
371
  generator: (data: any) => Target;
372
  /** Data source for animation */
373
  data: any;
374
  /** Update trigger */
375
  trigger?: "data" | "time" | "manual";
376
  /** Update interval for time-based triggers */
377
  interval?: number;
378
}
379
```
380

381
**Usage Examples:**
382

383
```typescript
384
import { createDynamicAnimation } from "motion/react";
385

386
function DynamicVisualization() {
387
  const data = [1, 4, 2, 8, 3, 6, 5];
388

389
  const chartAnimation = createDynamicAnimation({
390
    target: ".bar",
391
    generator: (values) => ({
392
      height: values.map(v => v * 10),
393
      backgroundColor: values.map(v => 
394
        v > 5 ? "#ef4444" : "#22c55e"
395
      )
396
    }),
397
    data: data,
398
    trigger: "data"
399
  });
400

401
  return (
402
    <div className="chart">
403
      {data.map((value, index) => (
404
        <motion.div
405
          key={index}
406
          className="bar"
407
          animate={chartAnimation}
408
          style={{
409
            width: 20,
410
            marginRight: 5,
411
            backgroundColor: "#6366f1"
412
          }}
413
        />
414
      ))}
415
    </div>
416
  );
417
}
418
```
419

420
### Performance Monitoring
421

422
Tools for monitoring animation performance and optimization.
423

424
```typescript { .api }
425
/**
426
 * Monitor animation performance
427
 * @param controls - Animation controls to monitor
428
 * @returns Performance metrics
429
 */
430
function useAnimationPerformance(
431
  controls: AnimationControls
432
): AnimationPerformanceMetrics;
433

434
interface AnimationPerformanceMetrics {
435
  /** Frames per second */
436
  fps: number;
437
  /** Frame time in milliseconds */
438
  frameTime: number;
439
  /** Dropped frames count */
440
  droppedFrames: number;
441
  /** Animation efficiency (0-1) */
442
  efficiency: number;
443
  /** GPU usage percentage */
444
  gpuUsage: number;
445
}
446
```