0
# Toaster Component
1

2
The main React component that renders and manages all toast notifications. The Toaster component should be included once in your application, typically at the root level, and will handle the display of all toast messages created throughout your app.
3

4
## Capabilities
5

6
### Toaster Component
7

8
The primary React component for rendering toast notifications with comprehensive configuration options.
9

10
```typescript { .api }
11
/**
12
 * React component that renders the toast notification container
13
 * @param props - Configuration options for the toaster
14
 * @param ref - Optional ref to the underlying HTML element
15
 */
16
const Toaster: React.ForwardRefExoticComponent<ToasterProps & React.RefAttributes<HTMLElement>>;
17

18
interface ToasterProps {
19
  /** Invert colors for dark backgrounds */
20
  invert?: boolean;
21
  /** Theme mode: light, dark, or system-based */
22
  theme?: "light" | "dark" | "system";
23
  /** Position of toast notifications on screen */
24
  position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center";
25
  /** Keyboard shortcut to expand toasts (default: ['altKey', 'KeyT']) */
26
  hotkey?: string[];
27
  /** Enable rich colors for enhanced visual styling */
28
  richColors?: boolean;
29
  /** Keep toasts expanded by default */
30
  expand?: boolean;
31
  /** Default duration for toasts in milliseconds */
32
  duration?: number;
33
  /** Gap between toast notifications in pixels */
34
  gap?: number;
35
  /** Maximum number of visible toasts at once */
36
  visibleToasts?: number;
37
  /** Show close button on all toasts */
38
  closeButton?: boolean;
39
  /** Default options applied to all toasts */
40
  toastOptions?: ToastOptions;
41
  /** Custom CSS class for the toaster container */
42
  className?: string;
43
  /** Custom styles for the toaster container */
44
  style?: React.CSSProperties;
45
  /** Offset from viewport edges */
46
  offset?: Offset;
47
  /** Mobile-specific offset from viewport edges */
48
  mobileOffset?: Offset;
49
  /** Text direction for RTL languages */
50
  dir?: "rtl" | "ltr" | "auto";
51
  /** Custom icons for different toast types */
52
  icons?: ToastIcons;
53
  /** ARIA label for the notification container */
54
  containerAriaLabel?: string;
55
  /** Pause toasts when browser tab is not visible */
56
  pauseWhenPageIsHidden?: boolean;
57
}
58

59
interface ToastOptions {
60
  /** Default CSS class for toast elements */
61
  className?: string;
62
  /** Show close button on toasts */
63
  closeButton?: boolean;
64
  /** Default CSS class for description text */
65
  descriptionClassName?: string;
66
  /** Default styles for toast container */
67
  style?: React.CSSProperties;
68
  /** Default styles for cancel buttons */
69
  cancelButtonStyle?: React.CSSProperties;
70
  /** Default styles for action buttons */
71
  actionButtonStyle?: React.CSSProperties;
72
  /** Default duration for all toasts */
73
  duration?: number;
74
  /** Disable default styling for all toasts */
75
  unstyled?: boolean;
76
  /** Default CSS classes for toast elements */
77
  classNames?: ToastClassnames;
78
}
79

80
type Offset = {
81
  top?: string | number;
82
  right?: string | number;
83
  bottom?: string | number;
84
  left?: string | number;
85
} | string | number;
86

87
interface ToastIcons {
88
  /** Icon for success toasts */
89
  success?: React.ReactNode;
90
  /** Icon for info toasts */
91
  info?: React.ReactNode;
92
  /** Icon for warning toasts */
93
  warning?: React.ReactNode;
94
  /** Icon for error toasts */
95
  error?: React.ReactNode;
96
  /** Icon for loading toasts */
97
  loading?: React.ReactNode;
98
  /** Icon for close button */
99
  close?: React.ReactNode;
100
}
101
```
102

103
## Usage Examples
104

105
### Basic Setup
106

107
```typescript
108
import React from "react";
109
import { Toaster, toast } from "sonner";
110

111
function App() {
112
  return (
113
    <div>
114
      {/* Add Toaster once in your app */}
115
      <Toaster />
116
      
117
      <main>
118
        {/* Your app content */}
119
        <button onClick={() => toast("Hello!")}>
120
          Show Toast
121
        </button>
122
      </main>
123
    </div>
124
  );
125
}
126
```
127

128
### Positioned Toaster
129

130
```typescript
131
import { Toaster } from "sonner";
132

133
// Top-right positioning
134
<Toaster position="top-right" />
135

136
// Bottom-center positioning
137
<Toaster position="bottom-center" />
138

139
// Top-left with custom offset
140
<Toaster 
141
  position="top-left" 
142
  offset={{ top: 20, left: 20 }}
143
/>
144
```
145

146
### Themed Toaster
147

148
```typescript
149
import { Toaster } from "sonner";
150

151
// Dark theme
152
<Toaster theme="dark" />
153

154
// System theme (follows OS preference)
155
<Toaster theme="system" />
156

157
// Rich colors enabled
158
<Toaster richColors />
159

160
// Inverted colors for dark backgrounds
161
<Toaster invert />
162
```
163

164
### Customized Toaster
165

166
```typescript
167
import { Toaster } from "sonner";
168

169
<Toaster
170
  position="top-center"
171
  toastOptions={{
172
    duration: 5000,
173
    style: {
174
      background: "#363636",
175
      color: "#fff",
176
    },
177
    className: "my-toast",
178
    actionButtonStyle: {
179
      background: "#007bff",
180
      color: "white",
181
    },
182
    cancelButtonStyle: {
183
      background: "#dc3545",
184
      color: "white",
185
    },
186
  }}
187
  closeButton
188
  richColors
189
  expand
190
  visibleToasts={5}
191
  gap={12}
192
/>
193
```
194

195
### Custom Icons
196

197
```typescript
198
import { Toaster } from "sonner";
199
import { CheckIcon, XIcon, InfoIcon } from "your-icon-library";
200

201
<Toaster
202
  icons={{
203
    success: <CheckIcon />,
204
    error: <XIcon />,
205
    info: <InfoIcon />,
206
    close: <XIcon size={12} />,
207
  }}
208
/>
209
```
210

211
### RTL Support
212

213
```typescript
214
import { Toaster } from "sonner";
215

216
// Right-to-left text direction
217
<Toaster dir="rtl" />
218

219
// Auto-detect from document
220
<Toaster dir="auto" />
221
```
222

223
### Accessibility Features
224

225
```typescript
226
import { Toaster } from "sonner";
227

228
<Toaster
229
  containerAriaLabel="Notifications"
230
  hotkey={["altKey", "KeyT"]} // Alt + T to expand toasts
231
  pauseWhenPageIsHidden={true} // Pause when tab not visible
232
/>
233
```
234

235
### Mobile Optimization
236

237
```typescript
238
import { Toaster } from "sonner";
239

240
<Toaster
241
  position="bottom-center"
242
  // Different offsets for mobile vs desktop
243
  offset="16px"
244
  mobileOffset="8px"
245
  // Fewer visible toasts on mobile
246
  visibleToasts={3}
247
  // Smaller gap on mobile
248
  gap={8}
249
/>
250
```
251

252
## Configuration Options
253

254
### Position Options
255

256
```typescript
257
type Position = 
258
  | "top-left" 
259
  | "top-right" 
260
  | "bottom-left" 
261
  | "bottom-right" 
262
  | "top-center" 
263
  | "bottom-center";
264
```
265

266
- **top-left**: Upper left corner
267
- **top-right**: Upper right corner (default)
268
- **bottom-left**: Lower left corner
269
- **bottom-right**: Lower right corner
270
- **top-center**: Top center
271
- **bottom-center**: Bottom center
272

273
### Theme Options
274

275
```typescript
276
type Theme = "light" | "dark" | "system";
277
```
278

279
- **light**: Light theme with bright backgrounds
280
- **dark**: Dark theme with dark backgrounds
281
- **system**: Automatically follows OS theme preference
282

283
### Offset Configuration
284

285
```typescript
286
// String or number for all sides
287
offset="20px"
288
offset={20}
289

290
// Object for individual sides
291
offset={{
292
  top: "20px",
293
  right: "16px",
294
  bottom: "20px",
295
  left: "16px"
296
}}
297
```
298

299
### Default Toast Options
300

301
All options in `ToastOptions` are applied as defaults to every toast:
302

303
```typescript
304
toastOptions={{
305
  // Default duration for all toasts
306
  duration: 5000,
307
  
308
  // Default styling
309
  style: { background: "#333" },
310
  className: "my-default-toast",
311
  
312
  // Default button styles
313
  actionButtonStyle: { background: "blue" },
314
  cancelButtonStyle: { background: "red" },
315
  
316
  // Show close button on all toasts
317
  closeButton: true,
318
  
319
  // Default classNames for elements
320
  classNames: {
321
    toast: "custom-toast",
322
    title: "custom-title",
323
    description: "custom-description"
324
  }
325
}}
326
```
327

328
## Advanced Configuration
329

330
### Keyboard Shortcuts
331

332
```typescript
333
// Default hotkey (Alt + T)
334
<Toaster hotkey={["altKey", "KeyT"]} />
335

336
// Custom hotkey (Ctrl + Shift + N)
337
<Toaster hotkey={["ctrlKey", "shiftKey", "KeyN"]} />
338

339
// Multiple keys
340
<Toaster hotkey={["metaKey", "KeyK"]} /> // Cmd/Win + K
341
```
342

343
### Performance Optimization
344

345
```typescript
346
<Toaster
347
  // Limit visible toasts for performance
348
  visibleToasts={3}
349
  
350
  // Pause when page is hidden to save resources
351
  pauseWhenPageIsHidden={true}
352
  
353
  // Smaller gap reduces layout recalculations
354
  gap={8}
355
/>
356
```
357

358
### Styling Integration
359

360
```typescript
361
// CSS Modules
362
<Toaster className={styles.toaster} />
363

364
// Tailwind CSS
365
<Toaster 
366
  className="font-sans"
367
  toastOptions={{
368
    className: "bg-white shadow-lg rounded-lg",
369
    actionButtonStyle: { background: "#3b82f6" }
370
  }}
371
/>
372

373
// Styled Components
374
const StyledToaster = styled(Toaster)`
375
  /* Custom styles */
376
`;
377
```
378

379
## Common Patterns
380

381
### App-wide Toaster Setup
382

383
```typescript
384
// _app.tsx (Next.js) or App.tsx (Create React App)
385
import { Toaster } from "sonner";
386

387
export default function App() {
388
  return (
389
    <>
390
      <YourAppContent />
391
      <Toaster 
392
        position="top-right"
393
        theme="system"
394
        richColors
395
        closeButton
396
        pauseWhenPageIsHidden
397
      />
398
    </>
399
  );
400
}
401
```
402

403
### Context-based Theme
404

405
```typescript
406
import { useTheme } from "your-theme-context";
407
import { Toaster } from "sonner";
408

409
function ThemedToaster() {
410
  const { theme } = useTheme();
411
  
412
  return <Toaster theme={theme} />;
413
}
414
```
415

416
### Conditional Rendering
417

418
```typescript
419
import { Toaster } from "sonner";
420

421
function App() {
422
  const showToaster = process.env.NODE_ENV === "development" || isProduction;
423
  
424
  return (
425
    <div>
426
      <YourApp />
427
      {showToaster && <Toaster />}
428
    </div>
429
  );
430
}
431
```