0
# Core Toast Functions
1

2
Primary toast creation functions for displaying notifications with different visual styles and behaviors. These functions provide the main interface for creating toast messages throughout your application.
3

4
## Capabilities
5

6
### Default Toast Function
7

8
Creates a basic toast notification with customizable options.
9

10
```typescript { .api }
11
/**
12
 * Creates a basic toast notification
13
 * @param message - The message to display (string or React element)
14
 * @param options - Optional configuration for the toast
15
 * @returns Unique identifier for the created toast
16
 */
17
function toast(message: string | React.ReactNode, options?: ExternalToast): string | number;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { toast } from "sonner";
24

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

28
// React element message
29
toast(<div>Custom <strong>HTML</strong> content</div>);
30

31
// With options
32
toast("Custom duration", { duration: 5000 });
33

34
// With description
35
toast("Main message", { 
36
  description: "Additional details about this notification" 
37
});
38

39
// With action button
40
toast("Do something", {
41
  action: {
42
    label: "Undo",
43
    onClick: () => console.log("Undo clicked")
44
  }
45
});
46
```
47

48
### Success Toast
49

50
Creates a success toast with green styling and checkmark icon.
51

52
```typescript { .api }
53
/**
54
 * Creates a success toast notification
55
 * @param message - The success message to display
56
 * @param options - Optional configuration for the toast
57
 * @returns Unique identifier for the created toast
58
 */
59
function toast.success(message: string | React.ReactNode, options?: ExternalToast): string | number;
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
import { toast } from "sonner";
66

67
// Simple success message
68
toast.success("Operation completed successfully!");
69

70
// Success with description
71
toast.success("User created", { 
72
  description: "New user has been added to the system" 
73
});
74

75
// Success with custom duration
76
toast.success("Saved!", { duration: 2000 });
77
```
78

79
### Error Toast
80

81
Creates an error toast with red styling and error icon.
82

83
```typescript { .api }
84
/**
85
 * Creates an error toast notification
86
 * @param message - The error message to display
87
 * @param options - Optional configuration for the toast
88
 * @returns Unique identifier for the created toast
89
 */
90
function toast.error(message: string | React.ReactNode, options?: ExternalToast): string | number;
91
```
92

93
**Usage Examples:**
94

95
```typescript
96
import { toast } from "sonner";
97

98
// Simple error message
99
toast.error("Something went wrong!");
100

101
// Error with description
102
toast.error("Failed to save", { 
103
  description: "Please check your internet connection and try again" 
104
});
105

106
// Error with action button
107
toast.error("Upload failed", {
108
  action: {
109
    label: "Retry",
110
    onClick: () => retryUpload()
111
  }
112
});
113
```
114

115
### Info Toast
116

117
Creates an info toast with blue styling and info icon.
118

119
```typescript { .api }
120
/**
121
 * Creates an info toast notification
122
 * @param message - The info message to display
123
 * @param options - Optional configuration for the toast
124
 * @returns Unique identifier for the created toast
125
 */
126
function toast.info(message: string | React.ReactNode, options?: ExternalToast): string | number;
127
```
128

129
**Usage Examples:**
130

131
```typescript
132
import { toast } from "sonner";
133

134
// Simple info message
135
toast.info("New update available");
136

137
// Info with description
138
toast.info("System maintenance", { 
139
  description: "Scheduled maintenance will begin at 2 AM EST" 
140
});
141
```
142

143
### Warning Toast
144

145
Creates a warning toast with yellow/orange styling and warning icon.
146

147
```typescript { .api }
148
/**
149
 * Creates a warning toast notification
150
 * @param message - The warning message to display
151
 * @param options - Optional configuration for the toast
152
 * @returns Unique identifier for the created toast
153
 */
154
function toast.warning(message: string | React.ReactNode, options?: ExternalToast): string | number;
155
```
156

157
**Usage Examples:**
158

159
```typescript
160
import { toast } from "sonner";
161

162
// Simple warning message
163
toast.warning("Low disk space");
164

165
// Warning with description
166
toast.warning("Unsaved changes", { 
167
  description: "You have unsaved changes that will be lost" 
168
});
169
```
170

171
### Loading Toast
172

173
Creates a loading toast with spinner icon that persists until manually dismissed or updated.
174

175
```typescript { .api }
176
/**
177
 * Creates a loading toast notification with spinner
178
 * @param message - The loading message to display
179
 * @param options - Optional configuration for the toast
180
 * @returns Unique identifier for the created toast
181
 */
182
function toast.loading(message: string | React.ReactNode, options?: ExternalToast): string | number;
183
```
184

185
**Usage Examples:**
186

187
```typescript
188
import { toast } from "sonner";
189

190
// Simple loading message
191
const loadingId = toast.loading("Uploading file...");
192

193
// Later, update or dismiss the loading toast
194
setTimeout(() => {
195
  toast.success("File uploaded successfully!", { id: loadingId });
196
}, 3000);
197

198
// Loading with custom message
199
toast.loading("Processing your request...");
200
```
201

202
### Message Toast
203

204
Alias for the default toast function, providing semantic clarity.
205

206
```typescript { .api }
207
/**
208
 * Creates a message toast notification (alias for default toast)
209
 * @param message - The message to display
210
 * @param options - Optional configuration for the toast
211
 * @returns Unique identifier for the created toast
212
 */
213
function toast.message(message: string | React.ReactNode, options?: ExternalToast): string | number;
214
```
215

216
### Dismiss Toast
217

218
Dismisses one or all toast notifications.
219

220
```typescript { .api }
221
/**
222
 * Dismisses toast notifications
223
 * @param id - Optional ID of specific toast to dismiss. If omitted, dismisses all toasts
224
 * @returns The ID that was dismissed, or undefined if dismissing all
225
 */
226
function toast.dismiss(id?: string | number): string | number | undefined;
227
```
228

229
**Usage Examples:**
230

231
```typescript
232
import { toast } from "sonner";
233

234
// Dismiss specific toast
235
const toastId = toast("This will be dismissed");
236
setTimeout(() => {
237
  toast.dismiss(toastId);
238
}, 2000);
239

240
// Dismiss all toasts
241
toast.dismiss();
242

243
// Common pattern: dismiss after action
244
toast("File uploaded", {
245
  action: {
246
    label: "View",
247
    onClick: () => {
248
      openFile();
249
      toast.dismiss(); // Clear all toasts when navigating
250
    }
251
  }
252
});
253
```
254

255
## Toast Options
256

257
### ExternalToast Interface
258

259
Configuration options available for all toast functions.
260

261
```typescript { .api }
262
interface ExternalToast {
263
  /** Custom ID for the toast (auto-generated if not provided) */
264
  id?: string | number;
265
  /** Custom icon to display instead of the default type icon */
266
  icon?: React.ReactNode;
267
  /** Rich colors mode for enhanced visual styling */
268
  richColors?: boolean;
269
  /** Invert the color scheme for dark backgrounds */
270
  invert?: boolean;
271
  /** Show close button on the toast */
272
  closeButton?: boolean;
273
  /** Whether the toast can be dismissed by user interaction */
274
  dismissible?: boolean;
275
  /** Additional description text displayed below the main message */
276
  description?: (() => React.ReactNode) | React.ReactNode;
277
  /** Duration in milliseconds before auto-dismiss (default: 4000) */
278
  duration?: number;
279
  /** Action button configuration */
280
  action?: Action | React.ReactNode;
281
  /** Cancel button configuration */
282
  cancel?: Action | React.ReactNode;
283
  /** Callback fired when toast is dismissed */
284
  onDismiss?: (toast: ToastT) => void;
285
  /** Callback fired when toast auto-closes */
286
  onAutoClose?: (toast: ToastT) => void;
287
  /** Custom styles for cancel button */
288
  cancelButtonStyle?: React.CSSProperties;
289
  /** Custom styles for action button */
290
  actionButtonStyle?: React.CSSProperties;
291
  /** Custom styles for the toast container */
292
  style?: React.CSSProperties;
293
  /** Disable default styling */
294
  unstyled?: boolean;
295
  /** Custom CSS class for the toast */
296
  className?: string;
297
  /** Custom CSS classes for toast elements */
298
  classNames?: ToastClassnames;
299
  /** Custom CSS class for description text */
300
  descriptionClassName?: string;
301
  /** Override global position for this specific toast */
302
  position?: Position;
303
}
304

305
interface Action {
306
  /** Text or React element to display on the button */
307
  label: React.ReactNode;
308
  /** Click handler for the button */
309
  onClick: (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;
310
  /** Custom styles for this action button */
311
  actionButtonStyle?: React.CSSProperties;
312
}
313
```
314

315
## Common Patterns
316

317
### Toast with Actions
318

319
```typescript
320
// Undo action
321
toast("Item deleted", {
322
  action: {
323
    label: "Undo",
324
    onClick: () => restoreItem()
325
  }
326
});
327

328
// Multiple buttons using cancel and action
329
toast("Confirm deletion?", {
330
  cancel: {
331
    label: "Cancel",
332
    onClick: () => console.log("Cancelled")
333
  },
334
  action: {
335
    label: "Delete",
336
    onClick: (event) => {
337
      deleteItem();
338
      // event.preventDefault() prevents auto-dismiss
339
    }
340
  }
341
});
342
```
343

344
### Persistent Toasts
345

346
```typescript
347
// Toast that doesn't auto-dismiss
348
toast("Important message", { duration: Infinity });
349

350
// Loading toast (automatically persistent)
351
const loadingId = toast.loading("Processing...");
352

353
// Update the persistent toast later
354
toast.success("Done!", { id: loadingId });
355
```
356

357
### Custom Styling
358

359
```typescript
360
// Custom styles
361
toast.success("Styled toast", {
362
  style: {
363
    background: "green",
364
    color: "white",
365
    border: "none"
366
  },
367
  className: "my-custom-toast"
368
});
369

370
// Custom class names for elements
371
toast("Detailed styling", {
372
  classNames: {
373
    toast: "custom-toast-container",
374
    title: "custom-title",
375
    description: "custom-description"
376
  }
377
});
378
```