0
# React Motion
1

2
React Motion is a spring-based animation library for React applications that uses spring physics instead of traditional easing curves and durations to create natural, fluid animations. The library provides three core components and utility functions for creating sophisticated animations that feel more responsive and natural when interrupted or adapted to changing conditions.
3

4
## Package Information
5

6
- **Package Name**: react-motion
7
- **Package Type**: npm
8
- **Language**: JavaScript (with Flow types)
9
- **Installation**: `npm install --save react-motion`
10

11
## Core Imports
12

13
```javascript
14
import { Motion, StaggeredMotion, TransitionMotion, spring, presets, stripStyle, reorderKeys } from 'react-motion';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Motion, StaggeredMotion, TransitionMotion, spring, presets, stripStyle, reorderKeys } = require('react-motion');
21
```
22

23
## Basic Usage
24

25
```javascript
26
import React from 'react';
27
import { Motion, spring } from 'react-motion';
28

29
function AnimatedComponent() {
30
  return (
31
    <Motion defaultStyle={{x: 0}} style={{x: spring(10)}}>
32
      {value => <div style={{transform: `translateX(${value.x}px)`}}>Animated!</div>}
33
    </Motion>
34
  );
35
}
36
```
37

38
## Architecture
39

40
React Motion is built around several key principles:
41

42
- **Physics-Based Animation**: Uses spring-damper physics instead of time-based easing
43
- **Interruption-Safe**: Animations can be seamlessly interrupted and redirected
44
- **Declarative API**: Specify target values, not animation durations
45
- **Performance Optimized**: Uses requestAnimationFrame and efficient batching
46
- **Component-Based**: Three specialized components for different animation scenarios
47

48
## Capabilities
49

50
### Basic Animation
51

52
Single element animations with spring physics. Ideal for simple state transitions, hover effects, and basic UI animations.
53

54
```javascript { .api }
55
class Motion extends React.Component {
56
  static propTypes = {
57
    defaultStyle: PropTypes.objectOf(PropTypes.number),
58
    style: PropTypes.objectOf(PropTypes.oneOfType([
59
      PropTypes.number,
60
      PropTypes.object,
61
    ])).isRequired,
62
    children: PropTypes.func.isRequired,
63
    onRest: PropTypes.func,
64
  };
65
}
66
```
67

68
[Motion Component](./motion.md)
69

70
### Staggered Animation
71

72
Cascading animations where each element's motion depends on the previous element. Perfect for list transitions and domino effects.
73

74
```javascript { .api }
75
class StaggeredMotion extends React.Component {
76
  static propTypes = {
77
    defaultStyles: PropTypes.arrayOf(PropTypes.objectOf(PropTypes.number)),
78
    styles: PropTypes.func.isRequired,
79
    children: PropTypes.func.isRequired,
80
  };
81
}
82
```
83

84
[StaggeredMotion Component](./staggered-motion.md)
85

86
### Transition Animation
87

88
Advanced component for animating mounting and unmounting elements with full lifecycle control. Essential for dynamic lists and complex UI transitions.
89

90
```javascript { .api }
91
class TransitionMotion extends React.Component {
92
  static propTypes = {
93
    defaultStyles: PropTypes.arrayOf(PropTypes.shape({
94
      key: PropTypes.string.isRequired,
95
      data: PropTypes.any,
96
      style: PropTypes.objectOf(PropTypes.number).isRequired,
97
    })),
98
    styles: PropTypes.oneOfType([
99
      PropTypes.func,
100
      PropTypes.arrayOf(PropTypes.shape({
101
        key: PropTypes.string.isRequired,
102
        data: PropTypes.any,
103
        style: PropTypes.objectOf(PropTypes.oneOfType([
104
          PropTypes.number,
105
          PropTypes.object,
106
        ])).isRequired,
107
      }))
108
    ]).isRequired,
109
    children: PropTypes.func.isRequired,
110
    willEnter: PropTypes.func,
111
    willLeave: PropTypes.func,
112
    didLeave: PropTypes.func,
113
  };
114
}
115
```
116

117
[TransitionMotion Component](./transition-motion.md)
118

119
### Spring Configuration
120

121
Spring physics configuration system for controlling animation behavior.
122

123
```javascript { .api }
124
function spring(val/*: number */, config/*?: SpringHelperConfig */)/*: OpaqueConfig */;
125

126
// Type definitions (Flow syntax):
127
/*::
128
type SpringHelperConfig = {
129
  stiffness?: number,
130
  damping?: number,
131
  precision?: number,
132
};
133

134
type OpaqueConfig = {
135
  val: number,
136
  stiffness: number,
137
  damping: number,
138
  precision: number,
139
};
140
*/
141

142
// Preset configurations for spring physics
143
const presets = {
144
  noWobble: {stiffness: 170, damping: 26}, // default
145
  gentle: {stiffness: 120, damping: 14},
146
  wobbly: {stiffness: 180, damping: 12},
147
  stiff: {stiffness: 210, damping: 20},
148
};
149
```
150

151
[Spring System](./spring-system.md)
152

153
### Utility Functions
154

155
Helper functions for working with spring configurations and style objects.
156

157
```javascript { .api }
158
function stripStyle(style/*: Style */)/*: PlainStyle */;
159
function reorderKeys()/*: void */; // DEPRECATED
160
```
161

162
**stripStyle**: Extracts plain numeric values from spring-configured style objects. Useful for getting initial values or converting spring styles to plain styles.
163

164
**reorderKeys**: Deprecated function that shows warning message. No longer needed for TransitionMotion's new styles array API.
165

166
## Core Types
167

168
```javascript { .api }
169
// Core type definitions (Flow syntax):
170
/*::
171
// Style object that can contain numbers or spring configurations
172
type Style = {[key: string]: number | OpaqueConfig};
173

174
// Plain numeric style object (interpolated values)
175
type PlainStyle = {[key: string]: number};
176

177
// Spring configuration object (internal use)
178
type OpaqueConfig = {
179
  val: number,
180
  stiffness: number,
181
  damping: number,
182
  precision: number,
183
};
184

185
// Additional types for TransitionMotion
186
type TransitionStyle = {
187
  key: string,
188
  data?: any,
189
  style: Style,
190
};
191

192
type TransitionPlainStyle = {
193
  key: string,
194
  data?: any,
195
  style: PlainStyle,
196
};
197
*/
198
```
199

200
## Dependencies
201

202
- `performance-now`: `^0.2.0` - High-resolution timing for animation frames
203
- `prop-types`: `^15.5.8` - Runtime type checking for React props
204
- `raf`: `^3.1.0` - RequestAnimationFrame polyfill for older browsers
205

206
## Peer Dependencies
207

208
- React: `^0.14.9 || ^15.3.0 || ^16.0.0`
209

210
## Platform Support
211

212
- Browser environments with React
213
- React Native v0.18+
214
- Server-side rendering compatible (with appropriate polyfills)