useToast

React hook for programmatically triggering toast notifications

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

items · ToastItem[]

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
}

config · ToastConfig

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 display
• options (ToastOptions, optional):
  • title (string, optional): Optional title above the message
  • duration (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 display
• options (ToastOptions, optional):
  • title (string, optional): Optional title above the message
  • duration (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 display
• options (ToastOptions, optional):
  • title (string, optional): Optional title above the message
  • duration (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 display
• options (ToastOptions, optional):
  • title (string, optional): Optional title above the message
  • duration (number, optional): Custom duration in milliseconds

Example:

toast.warning('Unsaved changes will be lost')
toast.warning('Low disk space', { title: 'Warning' })

remove · (id: string) => void

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.

clear · () => void

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>
    </>
  )
}

Form validation

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>
  // ...
}

Always ensure your components are wrapped with ToastProvider:

import { ToastProvider } from 'laravel-inertia-toast/react'

function App() {
  return (
    <ToastProvider>
      <ComponentUsingToast /> {/* Now this works! */}
    </ToastProvider>
  )
}