0
# Motion
1

2
Motion is a comprehensive animation library for JavaScript, React, and Vue applications, providing a unified API across all three frameworks. It features a hybrid engine that combines JavaScript flexibility with native browser APIs to deliver GPU-accelerated animations at 120fps, making it highly performant for complex motion graphics and user interface animations.
3

4
## Package Information
5

6
- **Package Name**: motion
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install motion`
10

11
## Core Imports
12

13
Motion provides different entry points optimized for specific use cases:
14

15
**JavaScript/DOM animations:**
16
```typescript
17
import { animate, scroll, inView } from "motion";
18
```
19

20
**React animations:**
21
```typescript
22
import { motion, AnimatePresence, useAnimate } from "motion/react";
23
```
24

25
**React client components (HTML/SVG elements):**
26
```typescript
27
import { div, span, button, svg, circle } from "motion/react-client";
28
```
29

30
**Mini builds for smaller bundles:**
31
```typescript
32
import { animate } from "motion/mini";
33
import { useAnimate } from "motion/react-mini";
34
```
35

36
**Vue animations:**
37
```javascript
38
import { motion } from "motion-v";
39
```
40

41
**Debug utilities:**
42
```typescript
43
import { recordStats } from "motion/debug";
44
```
45

46
For CommonJS:
47
```javascript
48
const { animate, motion } = require("motion");
49
```
50

51
## Basic Usage
52

53
**JavaScript DOM animation:**
54
```typescript
55
import { animate } from "motion";
56

57
// Animate a DOM element
58
animate("#box", { x: 100, rotate: 45 }, { duration: 1 });
59

60
// Animate with spring physics
61
animate(".card", { scale: 1.1 }, { type: "spring", stiffness: 300 });
62
```
63

64
**React component animation:**
65
```typescript
66
import { motion } from "motion/react";
67

68
function AnimatedComponent() {
69
  return (
70
    <motion.div
71
      initial={{ opacity: 0, y: 50 }}
72
      animate={{ opacity: 1, y: 0 }}
73
      exit={{ opacity: 0, y: -50 }}
74
      transition={{ duration: 0.3 }}
75
    >
76
      Hello Motion!
77
    </motion.div>
78
  );
79
}
80
```
81

82
**Vue component animation:**
83
```vue
84
<script>
85
import { motion } from "motion-v";
86

87
export default {
88
  components: { motion }
89
};
90
</script>
91

92
<template>
93
  <motion.div 
94
    :animate="{ x: 100, rotate: 45 }"
95
    :transition="{ duration: 1 }"
96
  >
97
    Hello Motion!
98
  </motion.div>
99
</template>
100
```
101

102
**Scroll-triggered animation:**
103
```typescript
104
import { scroll } from "motion";
105

106
scroll(({ y }) => {
107
  // Animate based on scroll position
108
  animate("#parallax", { y: y.current * 0.5 });
109
});
110
```
111

112
## Architecture
113

114
Motion is built around several key components:
115

116
- **Hybrid Engine**: Blends JavaScript flexibility with native browser APIs for optimal performance
117
- **Multi-Framework Support**: Unified API across JavaScript, React, and Vue with framework-specific optimizations
118
- **Entry Point Optimization**: Different builds (main, mini, react, client) for various use cases
119
- **Animation Features**: Springs, keyframes, gestures, drag interactions, layout animations
120
- **Performance Features**: GPU acceleration, tree-shaking, lazy loading support
121

122
## Capabilities
123

124
### DOM Animation
125

126
Core DOM animation functionality for animating elements directly without framework dependencies. Provides imperative animation controls with spring physics and keyframe support.
127

128
```typescript { .api }
129
function animate(
130
  target: string | Element | Element[],
131
  keyframes: Keyframes,
132
  options?: AnimationOptions
133
): AnimationControls;
134

135
function scroll(
136
  onScroll: (info: ScrollInfo) => void,
137
  options?: ScrollOptions
138
): () => void;
139

140
function inView(
141
  element: string | Element,
142
  onStart: (entry: IntersectionObserverEntry) => void | Promise<void>,
143
  options?: InViewOptions
144
): () => void;
145
```
146

147
[DOM Animation](./dom-animation.md)
148

149
### React Components
150

151
React integration providing motion components, hooks, and utilities for creating animated user interfaces with declarative syntax and lifecycle management.
152

153
```typescript { .api }
154
const motion: {
155
  [K in keyof HTMLElementTagNameMap]: React.ForwardRefExoticComponent<
156
    HTMLMotionProps<K>
157
  >;
158
} & {
159
  [K in keyof SVGElementTagNameMap]: React.ForwardRefExoticComponent<
160
    SVGMotionProps<K>
161
  >;
162
};
163

164
function AnimatePresence(props: AnimatePresenceProps): JSX.Element;
165

166
function useAnimate(): [AnimationScope, AnimateFunction];
167
function useMotionValue<T>(initial: T): MotionValue<T>;
168
function useSpring(value: MotionValue<number>, config?: SpringOptions): MotionValue<number>;
169
```
170

171
[React Components](./react-components.md)
172

173
### Gestures and Interactions
174

175
Comprehensive gesture system for handling drag, pan, hover, and tap interactions with physics-based animations and constraint support.
176

177
```typescript { .api }
178
interface DragControls {
179
  start(event: React.PointerEvent | PointerEvent): void;
180
  stop(): void;
181
}
182

183
function useDragControls(): DragControls;
184

185
interface PanInfo {
186
  point: Point;
187
  delta: Point;
188
  offset: Point;
189
  velocity: Point;
190
}
191
```
192

193
[Gestures and Interactions](./gestures.md)
194

195
### Layout Animations
196

197
Automatic layout animations that handle position and size changes smoothly, including shared layout transitions and reorder animations.
198

199
```typescript { .api }
200
function LayoutGroup(props: LayoutGroupProps): JSX.Element;
201

202
interface Reorder {
203
  Group: React.ForwardRefExoticComponent<ReorderGroupProps>;
204
  Item: React.ForwardRefExoticComponent<ReorderItemProps>;
205
}
206
```
207

208
[Layout Animations](./layout-animations.md)
209

210
### Animation Controls
211

212
Imperative animation controls for complex sequences, timeline management, and dynamic animation orchestration.
213

214
```typescript { .api }
215
interface AnimationControls {
216
  start(definition: AnimationDefinition): Promise<void>;
217
  stop(): void;
218
  set(definition: Target): void;
219
  mount(): void;
220
  unmount(): void;
221
}
222

223
function useAnimationControls(): AnimationControls;
224
```
225

226
[Animation Controls](./animation-controls.md)
227

228
### Value System
229

230
Motion value system for creating, transforming, and composing animated values with reactive updates and performance optimization.
231

232
```typescript { .api }
233
interface MotionValue<T> {
234
  get(): T;
235
  set(v: T): void;
236
  on(eventName: string, callback: (latest: T) => void): () => void;
237
  destroy(): void;
238
}
239

240
function useTransform<T>(
241
  value: MotionValue<number>,
242
  inputRange: number[],
243
  outputRange: T[]
244
): MotionValue<T>;
245
```
246

247
[Value System](./value-system.md)
248

249
## Types
250

251
```typescript { .api }
252
interface AnimationOptions {
253
  duration?: number;
254
  delay?: number;
255
  ease?: Easing;
256
  type?: "spring" | "keyframes" | "tween";
257
  repeat?: number;
258
  repeatType?: "loop" | "reverse" | "mirror";
259
  repeatDelay?: number;
260
}
261

262
interface SpringOptions {
263
  stiffness?: number;
264
  damping?: number;
265
  mass?: number;
266
  bounce?: number;
267
  duration?: number;
268
}
269

270
type Keyframes = string | number | Array<string | number>;
271

272
type Easing = 
273
  | "linear"
274
  | "easeIn" 
275
  | "easeOut" 
276
  | "easeInOut"
277
  | "circIn"
278
  | "circOut"
279
  | "circInOut"
280
  | "backIn"
281
  | "backOut"
282
  | "backInOut"
283
  | "anticipate"
284
  | ((t: number) => number);
285

286
interface Point {
287
  x: number;
288
  y: number;
289
}
290

291
interface Box {
292
  x: number;
293
  y: number;
294
  width: number;
295
  height: number;
296
}
297

298
interface ScrollInfo {
299
  x: MotionValue<number>;
300
  y: MotionValue<number>;
301
  xProgress: MotionValue<number>;
302
  yProgress: MotionValue<number>;
303
}
304
```