0
# Single Element Animation
1

2
Core functionality for animating individual React elements with enter/leave/appear transitions. CSSMotion provides comprehensive lifecycle control over element animations with both CSS-based and JavaScript callback support.
3

4
## Capabilities
5

6
### CSSMotion Component
7

8
Main component for single element animations with full control over motion timing, CSS classes, and animation states.
9

10
```typescript { .api }
11
/**
12
 * Core motion component for single element animations
13
 * @param props - Configuration for motion behavior and callbacks
14
 * @returns React component that renders animated children
15
 */
16
export default function CSSMotion(props: CSSMotionProps): React.ReactElement;
17

18
interface CSSMotionProps {
19
  /** CSS class name prefix or object with phase-specific names */
20
  motionName?: MotionName;
21
  /** Controls element visibility and triggers transitions */
22
  visible?: boolean;
23
  /** Enable appear animation when component mounts */
24
  motionAppear?: boolean;
25
  /** Enable enter animation when visible changes to true */
26
  motionEnter?: boolean;
27
  /** Enable leave animation when visible changes to false */
28
  motionLeave?: boolean;
29
  /** Leave animation immediately without waiting for enter to finish */
30
  motionLeaveImmediately?: boolean;
31
  /** Maximum time in milliseconds for motion to complete */
32
  motionDeadline?: number;
33
  /** Create element in view even when invisible (display: none) */
34
  forceRender?: boolean;
35
  /** Remove element from DOM after leave animation completes */
36
  removeOnLeave?: boolean;
37
  /** CSS class applied to element after leave animation */
38
  leavedClassName?: string;
39
  /** Private props used by CSSMotionList */
40
  eventProps?: object;
41
  
42
  // Motion phase event handlers
43
  onAppearPrepare?: MotionPrepareEventHandler;
44
  onEnterPrepare?: MotionPrepareEventHandler;
45
  onLeavePrepare?: MotionPrepareEventHandler;
46
  
47
  onAppearStart?: MotionEventHandler;
48
  onEnterStart?: MotionEventHandler;
49
  onLeaveStart?: MotionEventHandler;
50
  
51
  onAppearActive?: MotionEventHandler;
52
  onEnterActive?: MotionEventHandler;
53
  onLeaveActive?: MotionEventHandler;
54
  
55
  onAppearEnd?: MotionEndEventHandler;
56
  onEnterEnd?: MotionEndEventHandler;
57
  onLeaveEnd?: MotionEndEventHandler;
58
  
59
  /** Called when final visible state changes */
60
  onVisibleChanged?: (visible: boolean) => void;
61
  
62
  /** Internal ref for advanced use cases */
63
  internalRef?: React.Ref<any>;
64
  
65
  /** Render function receiving props and ref */
66
  children?: (
67
    props: {
68
      visible?: boolean;
69
      className?: string;
70
      style?: React.CSSProperties;
71
      [key: string]: any;
72
    },
73
    ref: (node: any) => void,
74
  ) => React.ReactElement;
75
}
76
```
77

78
**Usage Examples:**
79

80
```typescript
81
import CSSMotion from "rc-motion";
82

83
// Basic fade animation
84
function FadeExample() {
85
  const [visible, setVisible] = useState(true);
86
  
87
  return (
88
    <CSSMotion
89
      visible={visible}
90
      motionName="fade"
91
      motionAppear
92
      motionEnter
93
      motionLeave
94
    >
95
      {({ style, className }) => (
96
        <div style={style} className={className}>
97
          Content that fades in/out
98
        </div>
99
      )}
100
    </CSSMotion>
101
  );
102
}
103

104
// Complex animation with callbacks
105
function ComplexAnimation() {
106
  return (
107
    <CSSMotion
108
      visible={true}
109
      motionName={{
110
        appear: 'slide-up',
111
        appearActive: 'slide-up-active',
112
        enter: 'slide-down',
113
        enterActive: 'slide-down-active',
114
        leave: 'slide-out',
115
        leaveActive: 'slide-out-active'
116
      }}
117
      motionDeadline={1000}
118
      onAppearStart={(element) => {
119
        console.log('Appear animation started');
120
        return { opacity: 0, transform: 'translateY(20px)' };
121
      }}
122
      onAppearActive={(element) => {
123
        console.log('Appear animation active');
124
        return { opacity: 1, transform: 'translateY(0)' };
125
      }}
126
      onAppearEnd={(element, event) => {
127
        console.log('Appear animation completed');
128
        return false; // Don't prevent other animations
129
      }}
130
    >
131
      {({ style, className, visible }) => (
132
        <div style={style} className={className}>
133
          {visible && "Animated content with callbacks"}
134
        </div>
135
      )}
136
    </CSSMotion>
137
  );
138
}
139
```
140

141
### Motion Name Configuration
142

143
Flexible system for defining CSS class names during different animation phases.
144

145
```typescript { .api }
146
type MotionName = string | {
147
  appear?: string;
148
  enter?: string;
149
  leave?: string;
150
  appearActive?: string;
151
  enterActive?: string;
152
  leaveActive?: string;
153
};
154
```
155

156
**String format**: Class names are generated as `${motionName}-${phase}` and `${motionName}-${phase}-active`.
157

158
**Object format**: Explicit class names for each phase and active state.
159

160
### Motion Event Handlers
161

162
Callback functions for different phases of animation lifecycle.
163

164
```typescript { .api }
165
/**
166
 * Prepare phase handler - called before animation starts
167
 * Used for measuring element dimensions or setting up initial state
168
 */
169
type MotionPrepareEventHandler = (
170
  element: HTMLElement,
171
) => Promise<any> | void;
172

173
/**
174
 * Motion event handler - called during animation phases
175
 * Can return CSS properties to apply during the phase
176
 */
177
type MotionEventHandler = (
178
  element: HTMLElement,
179
  event: MotionEvent,
180
) => React.CSSProperties | void;
181

182
/**
183
 * End event handler - called when animation phase completes
184
 * Return true to prevent default behavior
185
 */
186
type MotionEndEventHandler = (
187
  element: HTMLElement,
188
  event: MotionEvent,
189
) => boolean | void;
190

191
/**
192
 * Motion event extends browser events with deadline flag
193
 */
194
type MotionEvent = (TransitionEvent | AnimationEvent) & {
195
  deadline?: boolean;
196
};
197
```
198

199
### Motion Configuration
200

201
Advanced configuration options for fine-tuning motion behavior.
202

203
```typescript { .api }
204
type CSSMotionConfig = boolean | {
205
  transitionSupport?: boolean;
206
  forwardRef?: boolean; // Deprecated
207
};
208

209
/**
210
 * Generate CSSMotion component with custom configuration
211
 * @param config - Motion configuration or boolean for transition support
212
 * @returns Configured CSSMotion component
213
 */
214
function genCSSMotion(config: CSSMotionConfig): React.ComponentType<CSSMotionProps>;
215
```
216

217
### Internal State Interface
218

219
Internal state structure used by CSSMotion component.
220

221
```typescript { .api }
222
interface CSSMotionState {
223
  status?: MotionStatus;
224
  statusActive?: boolean;
225
  newStatus?: boolean;
226
  statusStyle?: React.CSSProperties;
227
  prevProps?: CSSMotionProps;
228
}
229

230
type MotionStatus = 'none' | 'appear' | 'enter' | 'leave';
231
```