0
# RC Motion
1

2
RC Motion is a React lifecycle controlled motion library that provides smooth, performant animations for enter/leave transitions, appearance animations, and list animations. It offers both CSS-based animations through dynamic class names and JavaScript-controlled animations through callback hooks, with automatic cleanup and cross-browser compatibility.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import CSSMotion, { CSSMotionList, Provider } from "rc-motion";
15
import type { CSSMotionProps, CSSMotionListProps, MotionEventHandler } from "rc-motion";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const CSSMotion = require("rc-motion");
22
const { CSSMotionList, Provider } = require("rc-motion");
23
```
24

25
## Basic Usage
26

27
```typescript
28
import CSSMotion from "rc-motion";
29

30
// Simple visibility toggle with CSS transitions
31
function AnimatedBox() {
32
  const [visible, setVisible] = useState(true);
33
  
34
  return (
35
    <CSSMotion
36
      visible={visible}
37
      motionName="fade"
38
      motionAppear
39
      onAppearStart={(element) => {
40
        console.log('Animation started');
41
      }}
42
    >
43
      {({ style, className }) => (
44
        <div style={style} className={className}>
45
          Animated content
46
        </div>
47
      )}
48
    </CSSMotion>
49
  );
50
}
51
```
52

53
## Architecture
54

55
RC Motion is built around several key components:
56

57
- **CSSMotion**: Core component for single element animations with full lifecycle control
58
- **CSSMotionList**: Specialized component for animating lists of keyed elements with add/remove/update transitions
59
- **Provider**: Context provider for global motion configuration and performance optimization
60
- **Motion Status System**: Comprehensive state management for animation phases (appear/enter/leave)
61
- **Cross-browser Support**: Vendor prefix handling and feature detection for maximum compatibility
62

63
## Capabilities
64

65
### Single Element Animation
66

67
Core functionality for animating individual React elements with enter/leave/appear transitions. Supports both CSS-based animations and JavaScript motion callbacks.
68

69
```typescript { .api }
70
export default function CSSMotion(props: CSSMotionProps): React.ReactElement;
71

72
interface CSSMotionProps {
73
  motionName?: MotionName;
74
  visible?: boolean;
75
  motionAppear?: boolean;
76
  motionEnter?: boolean;
77
  motionLeave?: boolean;
78
  motionDeadline?: number;
79
  children?: (
80
    props: {
81
      visible?: boolean;
82
      className?: string;
83
      style?: React.CSSProperties;
84
      [key: string]: any;
85
    },
86
    ref: (node: any) => void,
87
  ) => React.ReactElement;
88
}
89

90
type MotionName = string | {
91
  appear?: string;
92
  enter?: string;
93
  leave?: string;
94
  appearActive?: string;
95
  enterActive?: string;
96
  leaveActive?: string;
97
};
98
```
99

100
[Single Element Animation](./css-motion.md)
101

102
### List Animation
103

104
Specialized component for animating arrays of keyed elements with smooth add/remove/reorder transitions. Automatically handles element lifecycle and position changes.
105

106
```typescript { .api }
107
export function CSSMotionList(props: CSSMotionListProps): React.ReactElement;
108

109
interface CSSMotionListProps extends Omit<CSSMotionProps, 'onVisibleChanged' | 'children'> {
110
  keys: (React.Key | { key: React.Key; [name: string]: any })[];
111
  component?: string | React.ComponentType | false;
112
  onVisibleChanged?: (visible: boolean, info: { key: React.Key }) => void;
113
  onAllRemoved?: () => void;
114
  children?: (
115
    props: {
116
      visible?: boolean;
117
      className?: string;
118
      style?: React.CSSProperties;
119
      index?: number;
120
      [key: string]: any;
121
    },
122
    ref: (node: any) => void,
123
  ) => React.ReactElement;
124
}
125
```
126

127
[List Animation](./css-motion-list.md)
128

129
### Global Configuration
130

131
Context provider for configuring motion behavior across your entire application. Enables performance optimizations and global motion controls.
132

133
```typescript { .api }
134
export function Provider(props: MotionContextProps & { children?: React.ReactNode }): React.ReactElement;
135

136
interface MotionContextProps {
137
  motion?: boolean;
138
}
139
```
140

141
[Motion Provider](./provider.md)
142

143
## Core Types
144

145
```typescript { .api }
146
// Motion event handlers
147
type MotionEventHandler = (
148
  element: HTMLElement,
149
  event: MotionEvent,
150
) => React.CSSProperties | void;
151

152
type MotionEndEventHandler = (
153
  element: HTMLElement,
154
  event: MotionEvent,
155
) => boolean | void;
156

157
type MotionPrepareEventHandler = (
158
  element: HTMLElement,
159
) => Promise<any> | void;
160

161
// Motion event with deadline support
162
type MotionEvent = (TransitionEvent | AnimationEvent) & {
163
  deadline?: boolean;
164
};
165

166
// Motion and step status constants
167
type MotionStatus = 'none' | 'appear' | 'enter' | 'leave';
168
type StepStatus = 'none' | 'prepare' | 'start' | 'active' | 'end' | 'prepared';
169
```