0
# Toast API
1

2
Core toast notification system providing a simple, flexible API for creating and managing toast notifications with type-specific methods, promise handling, and programmatic control.
3

4
## Capabilities
5

6
### Base Toast Function
7

8
Creates a default toast notification.
9

10
```typescript { .api }
11
/**
12
 * Creates a default toast notification
13
 * @param content - The content to display in the toast
14
 * @param options - Optional configuration for the toast
15
 * @returns Toast ID for programmatic control
16
 */
17
function toast<T = {}>(content: ToastContent<T>, options?: ToastOptions<T>): Id;
18
```
19

20
**Usage Example:**
21

22
```typescript
23
import { toast } from 'react-toastify';
24

25
// Simple text toast
26
toast("Hello World!");
27

28
// Toast with options
29
toast("Custom toast", {
30
  position: "top-center",
31
  autoClose: 5000,
32
  hideProgressBar: false,
33
  closeOnClick: true,
34
  pauseOnHover: true,
35
  draggable: true,
36
});
37

38
// Toast with React component
39
toast(<div>Custom <strong>HTML</strong> content</div>);
40

41
// Toast with render function
42
toast(({ closeToast }) => (
43
  <div>
44
    Custom content with <button onClick={closeToast}>Close</button>
45
  </div>
46
));
47
```
48

49
### Type-Specific Toast Methods
50

51
Convenient methods for creating toasts with predefined types and styling.
52

53
```typescript { .api }
54
/**
55
 * Creates a success toast with green styling and checkmark icon
56
 */
57
toast.success(content: ToastContent<T>, options?: ToastOptions<T>): Id;
58

59
/**
60
 * Creates an error toast with red styling and error icon
61
 */
62
toast.error(content: ToastContent<T>, options?: ToastOptions<T>): Id;
63

64
/**
65
 * Creates a warning toast with orange styling and warning icon
66
 */
67
toast.warning(content: ToastContent<T>, options?: ToastOptions<T>): Id;
68

69
/**
70
 * Alias for toast.warning
71
 */
72
toast.warn(content: ToastContent<T>, options?: ToastOptions<T>): Id;
73

74
/**
75
 * Creates an info toast with blue styling and info icon
76
 */
77
toast.info(content: ToastContent<T>, options?: ToastOptions<T>): Id;
78

79
/**
80
 * Creates a loading toast with spinner icon and no auto-close
81
 */
82
toast.loading(content: ToastContent<T>, options?: ToastOptions<T>): Id;
83

84
/**
85
 * Creates a toast with dark theme styling
86
 */
87
toast.dark(content: ToastContent<T>, options?: ToastOptions<T>): Id;
88
```
89

90
**Usage Examples:**
91

92
```typescript
93
// Type-specific toasts
94
toast.success("Operation completed successfully!");
95
toast.error("Something went wrong!");
96
toast.warning("Please check your input");
97
toast.info("New update available");
98

99
// Loading toast (doesn't auto-close)
100
const loadingId = toast.loading("Saving...");
101
// Later update or dismiss it
102
toast.dismiss(loadingId);
103
```
104

105
### Control Methods
106

107
Methods for programmatically controlling toast notifications.
108

109
```typescript { .api }
110
/**
111
 * Dismisses one or all toast notifications
112
 * @param id - Optional toast ID. If not provided, dismisses all toasts
113
 */
114
toast.dismiss(id?: Id): void;
115

116
/**
117
 * Updates an existing toast notification
118
 * @param id - The ID of the toast to update
119
 * @param options - New options to apply to the toast
120
 */
121
toast.update<T = {}>(id: Id, options: UpdateOptions<T>): void;
122

123
/**
124
 * Checks if a toast is currently active/visible
125
 * @param id - The toast ID to check
126
 * @param containerId - Optional container ID to check within
127
 * @returns True if the toast is active, false otherwise
128
 */
129
toast.isActive(id: Id, containerId?: Id): boolean;
130

131
/**
132
 * Clears the waiting queue of toasts
133
 * @param params - Optional parameters for selective clearing
134
 */
135
toast.clearWaitingQueue(params?: ClearWaitingQueueParams): void;
136

137
/**
138
 * Resumes toast timers (useful after pausing)
139
 * @param opts - Optional parameters
140
 */
141
toast.play(opts?: { id?: Id; containerId?: Id }): void;
142

143
/**
144
 * Pauses toast timers
145
 * @param opts - Optional parameters
146
 */
147
toast.pause(opts?: { id?: Id; containerId?: Id }): void;
148

149
/**
150
 * Marks a controlled progress toast as complete
151
 * @param id - The toast ID to mark as done
152
 */
153
toast.done(id: Id): void;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
// Store toast ID for later control
160
const toastId = toast("Processing...", { autoClose: false });
161

162
// Update the toast
163
toast.update(toastId, {
164
  render: "Processing complete!",
165
  type: "success",
166
  autoClose: 3000
167
});
168

169
// Check if toast is still active
170
if (toast.isActive(toastId)) {
171
  console.log("Toast is still visible");
172
}
173

174
// Dismiss specific toast
175
toast.dismiss(toastId);
176

177
// Dismiss all toasts
178
toast.dismiss();
179

180
// Clear waiting queue when limit is reached
181
toast.clearWaitingQueue();
182
```
183

184
### Promise Handling
185

186
Automatic handling of promise states with loading, success, and error toasts.
187

188
```typescript { .api }
189
/**
190
 * Handles promise states automatically with toast notifications
191
 * @param promise - Promise to monitor or function returning a promise
192
 * @param messages - Messages for different promise states
193
 * @param options - Optional configuration
194
 * @returns The original promise (for chaining)
195
 */
196
toast.promise<T, E = any, P = {}>(
197
  promise: Promise<T> | (() => Promise<T>),
198
  messages: ToastPromiseParams<T, E, P>,
199
  options?: ToastOptions<P>
200
): Promise<T>;
201

202
interface ToastPromiseParams<T = {}, E = {}, P = {}> {
203
  pending?: ToastContent<P> | UpdateOptions<P>;
204
  success?: ToastContent<T> | UpdateOptions<T> | ((data: T) => ToastContent<T> | UpdateOptions<T>);
205
  error?: ToastContent<E> | UpdateOptions<E> | ((error: E) => ToastContent<E> | UpdateOptions<E>);
206
}
207
```
208

209
**Usage Examples:**
210

211
```typescript
212
// Basic promise handling
213
const myPromise = fetch('/api/data');
214

215
toast.promise(
216
  myPromise,
217
  {
218
    pending: 'Loading data...',
219
    success: 'Data loaded successfully!',
220
    error: 'Failed to load data'
221
  }
222
);
223

224
// Advanced promise handling with custom options
225
toast.promise(
226
  fetch('/api/save'),
227
  {
228
    pending: {
229
      render: 'Saving your changes...',
230
      icon: false,
231
    },
232
    success: {
233
      render: 'Changes saved!',
234
      type: 'success',
235
      icon: '🎉',
236
      autoClose: 2000
237
    },
238
    error: {
239
      render: ({ data }) => {
240
        // Access error data
241
        return `Error: ${data.message}`;
242
      }
243
    }
244
  }
245
);
246

247
// Promise with dynamic content
248
toast.promise(
249
  uploadFile(file),
250
  {
251
    pending: 'Uploading file...',
252
    success: (data) => `File ${data.filename} uploaded successfully!`,
253
    error: (error) => `Upload failed: ${error.message}`
254
  }
255
);
256
```
257

258
### Event Subscription
259

260
Subscribe to toast lifecycle events for custom handling.
261

262
```typescript { .api }
263
/**
264
 * Subscribe to toast change events
265
 * @param callback - Function called when toasts are added, updated, or removed
266
 * @returns Unsubscribe function
267
 */
268
toast.onChange(callback: OnChangeCallback): () => void;
269

270
type OnChangeCallback = (payload: ToastItem) => void;
271

272
interface ToastItem<T = {}> {
273
  content: ToastContent<T>;
274
  id: Id;
275
  theme?: Theme;
276
  type?: TypeOptions;
277
  isLoading?: boolean;
278
  containerId?: Id;
279
  data: T;
280
  icon?: ToastIcon;
281
  status: ToastItemStatus;
282
}
283

284
type ToastItemStatus = 'added' | 'removed' | 'updated';
285
```
286

287
**Usage Example:**
288

289
```typescript
290
// Subscribe to toast changes
291
const unsubscribe = toast.onChange((payload) => {
292
  switch (payload.status) {
293
    case 'added':
294
      console.log('Toast added:', payload.id);
295
      break;
296
    case 'updated':
297
      console.log('Toast updated:', payload.id);
298
      break;
299
    case 'removed':
300
      console.log('Toast removed:', payload.id);
301
      break;
302
  }
303
});
304

305
// Later unsubscribe
306
unsubscribe();
307
```
308

309
## Support Types
310

311
```typescript { .api }
312
interface UpdateOptions<T = {}> extends Omit<ToastOptions<T>, 'toastId'> {
313
  render?: ToastContent<T>;
314
}
315

316
interface ClearWaitingQueueParams {
317
  containerId?: Id;
318
}
319

320
type DraggableDirection = 'x' | 'y';
321

322
type ToastIcon = 
323
  | React.ReactElement 
324
  | string 
325
  | number 
326
  | boolean 
327
  | ((props: IconProps) => React.ReactElement) 
328
  | false;
329
```