The useToast hook provides access to the toast context, allowing you to display notifications from anywhere in your React application.
Usage
import { useToast } from 'laravel-inertia-toast/react'
function MyComponent() {
const toast = useToast()
const handleSuccess = () => {
toast.success('Operation completed successfully!')
}
return (
<button onClick={handleSuccess}>
Click me
</button>
)
}
The useToast hook must be used within a component that is a child of ToastProvider. It will throw an error if used outside the provider context.
Return value
The hook returns a ToastContextValue object with the following properties and methods:
Properties
Array of currently active toast items. Each item contains:interface ToastItem {
id: string // Auto-generated unique identifier
message: string // Toast message content
level: ToastLevel // 'success' | 'error' | 'info' | 'warning'
title: string | null // Optional title
duration: number | null // Optional duration override
}
The current toast configuration:interface ToastConfig {
duration: number // Default: 5000ms
position: string // Default: 'top-right'
maxVisible: number // Default: 5
propKey: string // Default: 'toasts'
}
Methods
success
(message: string, options?: ToastOptions) => void
Display a success toast notification.Parameters:
message (string): The message to displayoptions (ToastOptions, optional):
title (string, optional): Optional title above the messageduration (number, optional): Custom duration in milliseconds
Example:toast.success('User created successfully')
toast.success('Profile updated', { title: 'Success' })
toast.success('Changes saved', { duration: 3000 })
error
(message: string, options?: ToastOptions) => void
Display an error toast notification.Parameters:
message (string): The error message to displayoptions (ToastOptions, optional):
title (string, optional): Optional title above the messageduration (number, optional): Custom duration in milliseconds
Example:toast.error('Failed to save changes')
toast.error('Invalid credentials', { title: 'Authentication Error' })
toast.error('Network error', { duration: 0 }) // No auto-dismiss
info
(message: string, options?: ToastOptions) => void
Display an informational toast notification.Parameters:
message (string): The informational message to displayoptions (ToastOptions, optional):
title (string, optional): Optional title above the messageduration (number, optional): Custom duration in milliseconds
Example:toast.info('Your session will expire in 5 minutes')
toast.info('New features available', { title: 'Update' })
warning
(message: string, options?: ToastOptions) => void
Display a warning toast notification.Parameters:
message (string): The warning message to displayoptions (ToastOptions, optional):
title (string, optional): Optional title above the messageduration (number, optional): Custom duration in milliseconds
Example:toast.warning('Unsaved changes will be lost')
toast.warning('Low disk space', { title: 'Warning' })
Remove a specific toast by its ID.Parameters:
id (string): The unique identifier of the toast to remove
Example:// Remove a specific toast
const toastId = toast.items[0]?.id
if (toastId) {
toast.remove(toastId)
}
You rarely need to use this method directly, as toasts auto-dismiss and have close buttons.
Remove all active toasts immediately.Example:// Clear all toasts when navigating away
const handleNavigation = () => {
toast.clear()
router.visit('/dashboard')
}
TypeScript types
type ToastLevel = 'success' | 'error' | 'info' | 'warning'
interface ToastOptions {
title?: string
duration?: number
}
interface ToastMessage {
message: string
level: ToastLevel
title: string | null
duration: number | null
}
interface ToastItem extends ToastMessage {
id: string
}
interface ToastConfig {
duration: number
position: string
maxVisible: number
propKey: string
}
interface ToastContextValue {
items: ToastItem[]
config: ToastConfig
success: (message: string, options?: ToastOptions) => void
error: (message: string, options?: ToastOptions) => void
info: (message: string, options?: ToastOptions) => void
warning: (message: string, options?: ToastOptions) => void
remove: (id: string) => void
clear: () => void
}
Examples
Basic toast notifications
import { useToast } from 'laravel-inertia-toast/react'
function UserForm() {
const toast = useToast()
const handleSubmit = async (data) => {
try {
await saveUser(data)
toast.success('User saved successfully')
} catch (error) {
toast.error('Failed to save user')
}
}
return <form onSubmit={handleSubmit}>...</form>
}
Toast with title
import { useToast } from 'laravel-inertia-toast/react'
function Dashboard() {
const toast = useToast()
const showWelcome = () => {
toast.success('Your account is now active', {
title: 'Welcome aboard!'
})
}
return <button onClick={showWelcome}>Show Welcome</button>
}
Custom duration
import { useToast } from 'laravel-inertia-toast/react'
function ImportantAlert() {
const toast = useToast()
const showCriticalError = () => {
// Error stays visible until manually dismissed
toast.error('Critical system error occurred', {
title: 'Error',
duration: 0
})
}
const showQuickNotice = () => {
// Disappears after 2 seconds
toast.info('Processing started', {
duration: 2000
})
}
return (
<>
<button onClick={showCriticalError}>Critical Error</button>
<button onClick={showQuickNotice}>Quick Notice</button>
</>
)
}
import { useToast } from 'laravel-inertia-toast/react'
import { useForm } from '@inertiajs/react'
function LoginForm() {
const toast = useToast()
const { data, setData, post, processing } = useForm({
email: '',
password: ''
})
const handleSubmit = (e) => {
e.preventDefault()
post('/login', {
onSuccess: () => {
toast.success('Login successful')
},
onError: (errors) => {
if (errors.email) {
toast.error(errors.email, { title: 'Validation Error' })
}
}
})
}
return <form onSubmit={handleSubmit}>...</form>
}
Clearing toasts on navigation
import { useToast } from 'laravel-inertia-toast/react'
import { router } from '@inertiajs/react'
import { useEffect } from 'react'
function MyComponent() {
const toast = useToast()
useEffect(() => {
// Clear all toasts when component unmounts
return () => toast.clear()
}, [])
const navigateAway = () => {
toast.clear()
router.visit('/dashboard')
}
return <button onClick={navigateAway}>Go to Dashboard</button>
}
Accessing current toasts
import { useToast } from 'laravel-inertia-toast/react'
function ToastDebugger() {
const { items, config } = useToast()
return (
<div>
<h3>Active Toasts: {items.length}</h3>
<p>Position: {config.position}</p>
<p>Max Visible: {config.maxVisible}</p>
<ul>
{items.map(item => (
<li key={item.id}>
[{item.level}] {item.message}
</li>
))}
</ul>
</div>
)
}
Error handling
The hook throws an error if used outside of ToastProvider:
import { useToast } from 'laravel-inertia-toast/react'
// This will throw an error
function ComponentOutsideProvider() {
const toast = useToast() // Error: useToast must be used within a <ToastProvider>
// ...
}
ToastProvider:
import { ToastProvider } from 'laravel-inertia-toast/react'
function App() {
return (
<ToastProvider>
<ComponentUsingToast /> {/* Now this works! */}
</ToastProvider>
)
}