0
# Animation and Transitions
1

2
Control the timing, easing, and visual behavior of expand/collapse animations for smooth, customizable user experiences.
3

4
## Capabilities
5

6
### Transition Timing Configuration
7

8
Fine-tune the duration and timing of opening and closing animations.
9

10
```typescript { .api }
11
/**
12
 * Duration in milliseconds for the opening transition
13
 * Controls how long it takes to expand the content
14
 * @default 400
15
 */
16
transitionTime?: number;
17

18
/**
19
 * Duration in milliseconds for the closing transition
20
 * If null, uses transitionTime for both directions
21
 * @default null
22
 */
23
transitionCloseTime?: number | null;
24
```
25

26
**Usage Examples:**
27

28
```jsx
29
// Fast animations
30
<Collapsible
31
  trigger="Quick toggle"
32
  transitionTime={200}
33
  transitionCloseTime={150}
34
>
35
  <p>Content with fast animations</p>
36
</Collapsible>
37

38
// Slow, dramatic animations
39
<Collapsible
40
  trigger="Slow reveal"
41
  transitionTime={1000}
42
  transitionCloseTime={800}
43
>
44
  <div>Content with slow, dramatic reveal</div>
45
</Collapsible>
46

47
// Asymmetric timing (fast open, slow close)
48
<Collapsible
49
  trigger="Asymmetric timing"
50
  transitionTime={300}
51
  transitionCloseTime={600}
52
>
53
  <p>Opens quickly, closes slowly</p>
54
</Collapsible>
55
```
56

57
### Easing and Animation Curves
58

59
Control the acceleration and deceleration of transitions using CSS timing functions.
60

61
```typescript { .api }
62
/**
63
 * CSS transition timing function for animations
64
 * Accepts any valid CSS easing value
65
 * @default "linear"
66
 */
67
easing?: string;
68
```
69

70
**Common Easing Values:**
71

72
- `"linear"` - Constant speed throughout
73
- `"ease"` - Slow start, fast middle, slow end
74
- `"ease-in"` - Slow start, accelerating
75
- `"ease-out"` - Fast start, decelerating
76
- `"ease-in-out"` - Slow start and end, fast middle
77
- `"cubic-bezier(0.4, 0, 0.2, 1)"` - Custom cubic bezier curve
78

79
**Usage Examples:**
80

81
```jsx
82
// Smooth, natural easing
83
<Collapsible
84
  trigger="Smooth animation"
85
  transitionTime={400}
86
  easing="ease-out"
87
>
88
  <p>Content with smooth easing</p>
89
</Collapsible>
90

91
// Bouncy animation with custom cubic-bezier
92
<Collapsible
93
  trigger="Bouncy reveal"
94
  transitionTime={600}
95
  easing="cubic-bezier(0.68, -0.55, 0.265, 1.55)"
96
>
97
  <div>Content with bouncy animation</div>
98
</Collapsible>
99

100
// Sharp, snappy transitions
101
<Collapsible
102
  trigger="Snappy toggle"
103
  transitionTime={250}
104
  easing="ease-in-out"
105
>
106
  <p>Quick, sharp transitions</p>
107
</Collapsible>
108
```
109

110
### Overflow Behavior Control
111

112
Configure how content overflow is handled during and after transitions.
113

114
```typescript { .api }
115
/**
116
 * CSS overflow value applied to content when fully opened
117
 * Controls scrolling and content visibility behavior
118
 * @default "hidden"
119
 */
120
overflowWhenOpen?: 
121
  | "hidden"    // Hide any overflow (default)
122
  | "visible"   // Show all content, may overlap other elements
123
  | "auto"      // Show scrollbars if needed
124
  | "scroll"    // Always show scrollbars
125
  | "inherit"   // Inherit from parent element
126
  | "initial"   // Use initial CSS value
127
  | "unset";    // Remove the property
128
```
129

130
**Usage Examples:**
131

132
```jsx
133
// Scrollable content when open
134
<Collapsible
135
  trigger="Scrollable content"
136
  overflowWhenOpen="auto"
137
>
138
  <div style={{ height: '400px', maxHeight: '200px' }}>
139
    <p>This content is taller than the max height</p>
140
    <p>Scrollbars will appear when expanded</p>
141
    <p>More content...</p>
142
  </div>
143
</Collapsible>
144

145
// Allow content to flow beyond container
146
<Collapsible
147
  trigger="Overflowing content"
148
  overflowWhenOpen="visible"
149
>
150
  <div style={{ width: '200%' }}>
151
    <p>This content extends beyond the container boundaries</p>
152
  </div>
153
</Collapsible>
154

155
// Always show scrollbars for consistent layout
156
<Collapsible
157
  trigger="Always scrollable"
158
  overflowWhenOpen="scroll"
159
>
160
  <div>
161
    <p>Scrollbars always visible for consistent spacing</p>
162
  </div>
163
</Collapsible>
164
```
165

166
## Animation State Management
167

168
The component internally manages complex animation states to ensure smooth transitions:
169

170
### Internal Animation States
171

172
The component tracks several internal states during animations:
173

174
- **`isClosed`**: Whether the component is visually closed
175
- **`inTransition`**: Whether an animation is currently running
176
- **`shouldOpenOnNextCycle`**: Flag for deferred opening operations
177
- **`shouldSwitchAutoOnNextCycle`**: Flag for height auto-switching
178
- **`height`**: Current height value (`0`, specific pixel value, or `"auto"`)
179
- **`transition`**: Current CSS transition property value
180

181
### Animation Lifecycle
182

183
1. **Opening Animation**:
184
   - State changes to `inTransition: true`
185
   - Height animates from `0` to content's `scrollHeight`
186
   - Once complete, height switches to `"auto"` for responsive behavior
187
   - `inTransition` becomes `false`
188

189
2. **Closing Animation**:
190
   - Height switches from `"auto"` to specific pixel value
191
   - Animates to `height: 0`
192
   - Component marked as `isClosed: true`
193
   - `inTransition` becomes `false`
194

195
### Performance Considerations
196

197
```jsx
198
// For better performance with expensive content
199
<Collapsible
200
  trigger="Performance optimized"
201
  lazyRender={true}              // Don't render until first open
202
  transitionTime={300}           // Shorter animations
203
  easing="ease-out"             // Smooth but not complex
204
  overflowWhenOpen="hidden"     // Simpler overflow handling
205
>
206
  <ExpensiveComponent />
207
</Collapsible>
208

209
// For complex, dynamic content
210
<Collapsible
211
  trigger="Dynamic content"
212
  transitionTime={400}
213
  overflowWhenOpen="auto"       // Allow scrolling if content changes size
214
  contentHiddenWhenClosed={true} // Better accessibility
215
>
216
  <DynamicContent />
217
</Collapsible>
218
```