0
# React Toastify
1

2
React Toastify is a comprehensive React notification library that enables developers to easily add toast notifications to their applications. It provides a highly customizable ToastContainer component and a simple toast API for displaying notifications with various types (success, error, warning, info), positions, animations, and styling options.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { toast, ToastContainer, Bounce, Slide, Zoom, Flip, Icons } from 'react-toastify';
15
import 'react-toastify/dist/ReactToastify.css';
16
```
17

18
For unstyled version (no default CSS):
19
```typescript
20
import { toast, ToastContainer } from 'react-toastify/unstyled';
21
```
22

23
For CommonJS:
24
```javascript
25
const { toast, ToastContainer, Bounce, Slide, Zoom, Flip, Icons } = require('react-toastify');
26
require('react-toastify/dist/ReactToastify.css');
27
```
28

29
## Basic Usage
30

31
```typescript
32
import React from 'react';
33
import { toast, ToastContainer } from 'react-toastify';
34
import 'react-toastify/dist/ReactToastify.css';
35

36
function App() {
37
  const notify = () => toast("Wow so easy!");
38

39
  return (
40
    <div>
41
      <button onClick={notify}>Notify!</button>
42
      <ToastContainer />
43
    </div>
44
  );
45
}
46
```
47

48
## Architecture
49

50
React Toastify is built around several key components:
51

52
- **Toast API**: Main `toast` function with type-specific methods (success, error, warning, etc.) and control methods
53
- **ToastContainer**: React component that renders and manages toast notifications with extensive configuration options
54
- **Transition System**: Built-in animation components (Bounce, Slide, Zoom, Flip) and custom transition support
55
- **Event System**: Subscribe to toast lifecycle events and manage toast state programmatically
56
- **Notification Center**: Optional addon for persistent notification management
57
- **Styling System**: Styled and unstyled variants with full theming support
58

59
## Capabilities
60

61
### Toast API
62

63
Core toast notification system with type-specific methods, promise handling, and programmatic control.
64

65
```typescript { .api }
66
function toast(content: ToastContent<T>, options?: ToastOptions<T>): Id;
67

68
// Type-specific methods
69
toast.success(content: ToastContent<T>, options?: ToastOptions<T>): Id;
70
toast.error(content: ToastContent<T>, options?: ToastOptions<T>): Id;
71
toast.warning(content: ToastContent<T>, options?: ToastOptions<T>): Id;
72
toast.info(content: ToastContent<T>, options?: ToastOptions<T>): Id;
73
toast.loading(content: ToastContent<T>, options?: ToastOptions<T>): Id;
74

75
// Control methods
76
toast.dismiss(id?: Id): void;
77
toast.update(id: Id, options: UpdateOptions<T>): void;
78
toast.isActive(id: Id, containerId?: Id): boolean;
79

80
// Promise handling
81
toast.promise<T>(
82
  promise: Promise<T> | (() => Promise<T>),
83
  messages: ToastPromiseParams<T>,
84
  options?: ToastOptions<T>
85
): Promise<T>;
86
```
87

88
[Toast API](./toast-api.md)
89

90
### Toast Container
91

92
Main React component for rendering and managing toast notifications with extensive configuration options.
93

94
```typescript { .api }
95
interface ToastContainerProps {
96
  position?: ToastPosition;
97
  autoClose?: number | false;
98
  closeOnClick?: boolean;
99
  pauseOnHover?: boolean;
100
  draggable?: boolean;
101
  hideProgressBar?: boolean;
102
  newestOnTop?: boolean;
103
  transition?: ToastTransition;
104
  theme?: Theme;
105
  // ... many more configuration options
106
}
107

108
function ToastContainer(props: ToastContainerProps): JSX.Element;
109
```
110

111
[Toast Container](./container.md)
112

113
### Built-in Transitions
114

115
Pre-built animation components for smooth toast transitions.
116

117
```typescript { .api }
118
const Bounce: React.FC<ToastTransitionProps>;
119
const Slide: React.FC<ToastTransitionProps>;
120
const Zoom: React.FC<ToastTransitionProps>;
121
const Flip: React.FC<ToastTransitionProps>;
122
```
123

124
[Transitions](./transitions.md)
125

126
### Utilities
127

128
Helper functions for creating custom transitions and animations.
129

130
```typescript { .api }
131
function cssTransition(config: CSSTransitionProps): React.FC<ToastTransitionProps>;
132
function collapseToast(node: HTMLElement, done: () => void, duration?: number): void;
133
```
134

135
[Utilities](./utilities.md)
136

137
### Icons
138

139
Built-in icon components for different toast types and loading states.
140

141
```typescript { .api }
142
const Icons: {
143
  info: React.FC<IconProps>;
144
  warning: React.FC<IconProps>;
145
  success: React.FC<IconProps>;
146
  error: React.FC<IconProps>;
147
  spinner: React.FC;
148
};
149

150
interface IconProps {
151
  theme: Theme;
152
  type: TypeOptions;
153
  isLoading?: boolean;
154
}
155
```
156

157
### Notification Center
158

159
Addon for persistent notification management with hooks-based API.
160

161
```typescript { .api }
162
function useNotificationCenter<T>(
163
  params?: UseNotificationCenterParams<T>
164
): UseNotificationCenter<T>;
165

166
interface UseNotificationCenter<T> {
167
  notifications: NotificationCenterItem<T>[];
168
  clear(): void;
169
  markAllAsRead(read?: boolean): void;
170
  markAsRead(id: Id | Id[], read?: boolean): void;
171
  remove(id: Id | Id[]): void;
172
  add(item: NotificationCenterItem<T>): void;
173
  update(id: Id, item: Partial<NotificationCenterItem<T>>): void;
174
  find(id: Id): NotificationCenterItem<T> | undefined;
175
  sort(compareFn: SortFn<T>): void;
176
  unreadCount: number;
177
}
178
```
179

180
[Notification Center](./notification-center.md)
181

182
## Core Types
183

184
```typescript { .api }
185
type Id = string | number;
186

187
type ToastContent<T = unknown> = 
188
  | React.ReactNode 
189
  | ((props: ToastContentProps<T>) => React.ReactNode);
190

191
type ToastPosition =
192
  | 'top-left'
193
  | 'top-right'
194
  | 'top-center'
195
  | 'bottom-left'
196
  | 'bottom-right'
197
  | 'bottom-center';
198

199
type Theme = 'light' | 'dark' | 'colored' | string;
200

201
type TypeOptions = 'info' | 'success' | 'warning' | 'error' | 'default';
202

203
interface ToastOptions<T = {}> {
204
  type?: TypeOptions;
205
  onOpen?: (props: ToastContentProps<T>) => void;
206
  onClose?: (props: ToastContentProps<T>) => void;
207
  autoClose?: number | false;
208
  closeButton?: boolean | ((props: CloseButtonProps) => React.ReactNode);
209
  position?: ToastPosition;
210
  transition?: ToastTransition;
211
  hideProgressBar?: boolean;
212
  pauseOnHover?: boolean;
213
  pauseOnFocusLoss?: boolean;
214
  closeOnClick?: boolean;
215
  draggable?: boolean;
216
  draggablePercent?: number;
217
  draggableDirection?: DraggableDirection;
218
  role?: string;
219
  theme?: Theme;
220
  containerId?: Id;
221
  toastId?: Id;
222
  updateId?: Id;
223
  data?: T;
224
  isLoading?: boolean;
225
  icon?: ToastIcon;
226
  delay?: number;
227
}
228

229
interface ToastContentProps<T = {}> {
230
  closeToast: CloseToastFunc;
231
  toastProps: ToastProps;
232
  isPaused: boolean;
233
  data: T;
234
}
235

236
interface ToastProps {
237
  position: ToastPosition;
238
  autoClose?: number | false;
239
  closeButton?: boolean | React.ReactElement | ((props: CloseButtonProps) => React.ReactNode);
240
  hideProgressBar?: boolean;
241
  closeOnClick?: boolean;
242
  pauseOnHover?: boolean;
243
  draggable?: boolean;
244
  theme?: Theme;
245
  type?: TypeOptions;
246
  toastId?: Id;
247
  containerId?: Id;
248
}
249

250
type CloseToastFunc = ((reason?: boolean | string) => void) & ((e: React.MouseEvent) => void);
251
```