Getting Started
React Toast Kit is a performant, accessible, and fully typed toast notification library. Install in seconds, configure once, call from anywhere.
Installation
npm install react-toast-kit
# or
pnpm add react-toast-kitCSS is auto-injected at runtime — no stylesheet import required.
Quick Start
Wrap your app once with ToastProvider, then call toast() from any component.
1. Add the provider
1// app/layout.tsx (Next.js App Router)
2import { ToastProvider } from 'react-toast-kit';
3
4export default function RootLayout({ children }) {
5 return (
6 <html lang="en">
7 <body>
8 <ToastProvider theme="system" position="top-right">
9 {children}
10 </ToastProvider>
11 </body>
12 </html>
13 );
14}2. Call toast() anywhere
1import { toast } from 'react-toast-kit';
2
3// Simple string
4toast('Hello world!');
5
6// With options
7toast.success({
8 title: 'Saved!',
9 description: 'Your changes have been saved.',
10 duration: 4000,
11 position: 'top-right',
12 animation: 'slide',
13});
14
15// Promise
16toast.promise(fetchData(), {
17 loading: 'Loading...',
18 success: (data) => `Got ${data.length} items`,
19 error: (err) => `Error: ${err.message}`,
20});
21
22// Update an existing toast
23const id = toast.loading('Processing...');
24toast.update(id, { variant: 'success', title: 'Done!' });ToastProvider Props
1<ToastProvider
2 theme="system" // 'light' | 'dark' | 'system'
3 position="top-right" // 6 positions available
4 maxToasts={5}
5 defaultDuration={4000}
6 defaultAnimation="slide"
7 defaultDismissible={true}
8 defaultPauseOnHover={true}
9 enableAccessibleAnnouncements={true}
10 topOffset={80} // account for fixed header
11>
12 {children}
13</ToastProvider>| Prop | Type | Default |
|---|---|---|
| theme | "light" | "dark" | "system" | "system" |
| position | ToastPosition | "top-right" |
| maxToasts | number | 3 |
| defaultDuration | number (ms) | 4000 |
| defaultAnimation | ToastAnimation | "slide" |
| defaultDismissible | boolean | true |
| defaultPauseOnHover | boolean | true |
| topOffset | number | 16 |
| bottomOffset | number | 16 |
| enableAccessibleAnnouncements | boolean | true |
Hooks
1import { useToast, useToastConfig, useToastStats } from 'react-toast-kit';
2
3// Full access
4const { toasts, theme, setTheme, addToast, removeToast } = useToast();
5
6// Lightweight — theme only
7const { theme, setTheme } = useToastConfig();
8
9// Analytics
10const { total, byVariant, byPosition } = useToastStats();Explore the Guides
Features
All toast types, animations, updates, and advanced patterns with live examples.
Theming
Light, dark, system themes. CSS custom properties, className, and inline styles.
Next.js
App Router & Pages Router setup. SSR safety and best practices for production.
Accessibility
ARIA roles, keyboard navigation, screen reader support, and reduced motion.
Patterns
Form validation, optimistic updates, undo actions, and real-world usage patterns.
FAQ
Does it work with Next.js App Router?
Yes. Wrap your root layout with ToastProvider and mark it as a client component, or create a separate client wrapper. See the Next.js guide.
Do I need to import a CSS file?
No. The default entry injects CSS automatically. For strict CSP, import from 'react-toast-kit/core' and add 'react-toast-kit/styles.css' to your global style entry.
Can I use custom components inside toasts?
Yes. Use toast.custom(<YourComponent />) to render any JSX inside the toast container with full styling control.
Is it accessible?
Yes. Toasts include ARIA roles (status / alert), aria-live regions, keyboard navigation, and respect prefers-reduced-motion.