0
# Utilities
1

2
Helper functions and utilities for creating custom transitions, animations, and advanced toast functionality. These utilities provide low-level building blocks for extending React Toastify's capabilities.
3

4
## Capabilities
5

6
### cssTransition Utility
7

8
Creates custom transition components using CSS classes for complete control over toast animations.
9

10
```typescript { .api }
11
/**
12
 * Creates a custom transition component using CSS classes
13
 * @param config - Configuration object defining CSS classes and timing
14
 * @returns Custom transition component ready to use with ToastContainer
15
 */
16
function cssTransition(config: CSSTransitionProps): React.FC<ToastTransitionProps>;
17

18
interface CSSTransitionProps {
19
  /** CSS class applied when toast is entering */
20
  enter: string;
21
  /** CSS class applied when toast is exiting */
22
  exit: string;
23
  /** Whether to append position-based classes (e.g. '--top-right') */
24
  appendPosition?: boolean;
25
  /** Enable height collapse animation on exit */
26
  collapse?: boolean;
27
  /** Duration for height collapse animation */
28
  collapseDuration?: number;
29
}
30
```
31

32
**Basic Custom Transition:**
33

34
```typescript
35
import { cssTransition, ToastContainer } from 'react-toastify';
36

37
// Create a custom fade transition
38
const FadeTransition = cssTransition({
39
  enter: 'fade-enter',
40
  exit: 'fade-exit',
41
  collapse: true,
42
  collapseDuration: 300
43
});
44

45
// Use with ToastContainer
46
<ToastContainer transition={FadeTransition} />
47
```
48

49
**Corresponding CSS:**
50

51
```css
52
.fade-enter {
53
  opacity: 0;
54
  animation: fadeIn 300ms ease-in-out;
55
}
56

57
.fade-exit {
58
  opacity: 1;
59
  animation: fadeOut 300ms ease-in-out;
60
}
61

62
@keyframes fadeIn {
63
  from { opacity: 0; }
64
  to { opacity: 1; }
65
}
66

67
@keyframes fadeOut {
68
  from { opacity: 1; }
69
  to { opacity: 0; }
70
}
71
```
72

73
**Advanced Custom Transition with Position Awareness:**
74

75
```typescript
76
const SlideTransition = cssTransition({
77
  enter: 'slide-enter',
78
  exit: 'slide-exit',
79
  appendPosition: true,  // Enables position-specific classes
80
  collapse: true,
81
  collapseDuration: 300
82
});
83
```
84

85
**Position-Aware CSS:**
86

87
```css
88
/* Base slide animations using CSS animations */
89
.slide-enter {
90
  animation: slideIn 400ms ease-out;
91
}
92

93
.slide-exit {
94
  animation: slideOut 200ms ease-in;
95
}
96

97
/* Position-specific entry animations */
98
.slide-enter--top-right,
99
.slide-enter--bottom-right {
100
  animation: slideInFromRight 400ms ease-out;
101
}
102

103
.slide-enter--top-left,
104
.slide-enter--bottom-left {
105
  animation: slideInFromLeft 400ms ease-out;
106
}
107

108
.slide-enter--top-center,
109
.slide-enter--bottom-center {
110
  animation: slideInFromTop 400ms ease-out;
111
}
112

113
@keyframes slideInFromRight {
114
  from { transform: translateX(100%); opacity: 0; }
115
  to { transform: translateX(0); opacity: 1; }
116
}
117

118
@keyframes slideInFromLeft {
119
  from { transform: translateX(-100%); opacity: 0; }
120
  to { transform: translateX(0); opacity: 1; }
121
}
122

123
@keyframes slideInFromTop {
124
  from { transform: translateY(-100%); opacity: 0; }
125
  to { transform: translateY(0); opacity: 1; }
126
}
127

128
@keyframes slideOut {
129
  from { opacity: 1; }
130
  to { opacity: 0; }
131
}
132
```
133

134
### collapseToast Utility
135

136
Low-level utility for animating toast height collapse, useful for custom implementations.
137

138
```typescript { .api }
139
/**
140
 * Animates the collapse of a toast element by reducing its height to zero
141
 * @param node - The HTML element to collapse
142
 * @param done - Callback function called when animation completes
143
 * @param duration - Animation duration in milliseconds (default: 300)
144
 */
145
function collapseToast(
146
  node: HTMLElement,
147
  done: () => void,
148
  duration?: number
149
): void;
150
```
151

152
**Usage Example:**
153

154
```typescript
155
import { collapseToast } from 'react-toastify';
156

157
// Custom collapse implementation
158
function customCollapseHandler(element: HTMLElement) {
159
  collapseToast(element, () => {
160
    console.log('Collapse animation completed');
161
    // Perform cleanup or additional actions
162
  }, 250);
163
}
164

165
// Use in custom transition
166
const CustomTransitionWithCollapse = cssTransition({
167
  enter: 'custom-enter',
168
  exit: 'custom-exit',
169
  collapse: true,  // Uses collapseToast internally
170
  collapseDuration: 250
171
});
172
```
173

174
**Manual Collapse Usage:**
175

176
```typescript
177
import React, { useRef } from 'react';
178
import { collapseToast } from 'react-toastify';
179

180
function CustomToastComponent() {
181
  const toastRef = useRef<HTMLDivElement>(null);
182

183
  const handleManualCollapse = () => {
184
    if (toastRef.current) {
185
      collapseToast(toastRef.current, () => {
186
        // Toast has fully collapsed
187
        console.log('Toast collapsed');
188
      });
189
    }
190
  };
191

192
  return (
193
    <div ref={toastRef} className="custom-toast">
194
      <p>Custom toast content</p>
195
      <button onClick={handleManualCollapse}>Collapse</button>
196
    </div>
197
  );
198
}
199
```
200

201
### Icon Utilities
202

203
Built-in icon components and utilities for toast icons.
204

205
```typescript { .api }
206
/**
207
 * Built-in icon components for different toast types
208
 */
209
const Icons: {
210
  info: React.FC<IconProps>;
211
  success: React.FC<IconProps>;
212
  warning: React.FC<IconProps>;
213
  error: React.FC<IconProps>;
214
  spinner: React.FC<IconProps>;
215
};
216

217
/**
218
 * Utility function to resolve the appropriate icon for a toast
219
 * @param params - Icon resolution parameters
220
 * @returns React element or null
221
 */
222
function getIcon(params: {
223
  theme: Theme;
224
  type: TypeOptions;
225
  isLoading?: boolean;
226
  icon?: ToastIcon;
227
}): React.ReactElement | null;
228

229
interface IconProps {
230
  theme: Theme;
231
  type: TypeOptions;
232
}
233
```
234

235
**Usage Examples:**
236

237
```typescript
238
import { Icons, getIcon } from 'react-toastify';
239

240
// Use built-in icons directly
241
function CustomToast() {
242
  return (
243
    <div>
244
      <Icons.success theme="light" type="success" />
245
      <span>Success message</span>
246
    </div>
247
  );
248
}
249

250
// Use icon resolution utility
251
const resolvedIcon = getIcon({
252
  theme: 'dark',
253
  type: 'error',
254
  isLoading: false
255
});
256

257
// Custom icon in toast options
258
toast.success("Success!", {
259
  icon: <Icons.success theme="colored" type="success" />
260
});
261
```
262

263
### CloseButton Component
264

265
Default close button component that can be customized or replaced.
266

267
```typescript { .api }
268
/**
269
 * Default close button component
270
 * @param props - Close button props
271
 * @returns JSX.Element - The close button
272
 */
273
function CloseButton(props: CloseButtonProps): JSX.Element;
274

275
interface CloseButtonProps {
276
  closeToast: (e: React.MouseEvent<HTMLElement>) => void;
277
  type: TypeOptions;
278
  ariaLabel?: string;
279
  theme: Theme;
280
}
281
```
282

283
**Custom Close Button Example:**
284

285
```typescript
286
import { CloseButton } from 'react-toastify';
287

288
// Extend the default close button
289
function CustomCloseButton(props: CloseButtonProps) {
290
  return (
291
    <button
292
      onClick={props.closeToast}
293
      className={`custom-close custom-close--${props.type}`}
294
      aria-label={props.ariaLabel || 'Close notification'}
295
    >
296
      ✕
297
    </button>
298
  );
299
}
300

301
// Use with ToastContainer
302
<ToastContainer closeButton={CustomCloseButton} />
303

304
// Or use with individual toasts
305
toast.info("Message", {
306
  closeButton: CustomCloseButton
307
});
308
```
309

310
### Type Validation Utilities
311

312
Internal utilities for runtime type checking and prop validation.
313

314
```typescript { .api }
315
/**
316
 * Validates toast options at runtime
317
 * @param options - Toast options to validate
318
 * @returns Validated options object
319
 */
320
function validateToastOptions<T>(options: ToastOptions<T>): ToastOptions<T>;
321

322
/**
323
 * Checks if a value is a valid toast content type
324
 * @param content - Content to validate
325
 * @returns Boolean indicating if content is valid
326
 */
327
function isValidToastContent(content: any): boolean;
328
```
329

330
**Usage in Custom Toast Components:**
331

332
```typescript
333
import { validateToastOptions, isValidToastContent } from 'react-toastify';
334

335
function customToastFunction(content: any, options: any) {
336
  // Validate inputs
337
  if (!isValidToastContent(content)) {
338
    throw new Error('Invalid toast content');
339
  }
340

341
  const validatedOptions = validateToastOptions(options || {});
342
  
343
  // Proceed with toast creation
344
  return toast(content, validatedOptions);
345
}
346
```
347

348
## Advanced Utility Patterns
349

350
### Custom Transition Builder
351

352
Create a utility for building themed transitions:
353

354
```typescript
355
function createThemedTransition(baseName: string, themes: string[]) {
356
  return cssTransition({
357
    enter: `${baseName}-enter`,
358
    exit: `${baseName}-exit`,
359
    appendPosition: true
360
  });
361
}
362

363
// Create themed transitions
364
const ThemedSlide = createThemedTransition('themed-slide', ['light', 'dark']);
365
```
366

367
### Animation Choreographer
368

369
Coordinate multiple animation phases:
370

371
```typescript
372
function createChoreographedTransition(phases: Array<{
373
  className: string;
374
}>) {
375
  return cssTransition({
376
    enter: phases[0].className,
377
    exit: phases[0].className.replace('enter', 'exit')
378
  });
379
}
380
```
381

382
### Responsive Transitions
383

384
Create transitions that adapt to screen size:
385

386
```typescript
387
const ResponsiveSlide = cssTransition({
388
  enter: 'responsive-slide-enter',
389
  exit: 'responsive-slide-exit',
390
  appendPosition: true
391
});
392

393
// CSS with media queries
394
/*
395
@media (max-width: 768px) {
396
  .responsive-slide-enter--top-right {
397
    transform: translateY(-100%) !important;
398
  }
399
}
400
*/
401
```
402

403
## Support Types
404

405
```typescript { .api }
406
type ToastTransition = React.FC<ToastTransitionProps>;
407

408
interface ToastTransitionProps {
409
  isIn: boolean;
410
  done: () => void;
411
  position: ToastPosition;
412
  preventExitTransition?: boolean;
413
  nodeRef: React.RefObject<HTMLElement>;
414
  children?: React.ReactNode;
415
}
416

417
type ToastIcon = 
418
  | React.ReactElement 
419
  | string 
420
  | number 
421
  | boolean 
422
  | ((props: IconProps) => React.ReactElement) 
423
  | false;
424
```