React

Set up Laravel Inertia Toast with React

Learn how to integrate Laravel Inertia Toast with React. This guide covers provider setup, component configuration, and usage of the useToast hook.

Installation

First, install the React package:

npm install @laravel-inertia-toast/react

Setup

1. Wrap your app with ToastProvider

   In your main application file (typically app.jsx or app.tsx), import and wrap your application with the ToastProvider:

   import { createRoot } from 'react-dom/client'
   import { createInertiaApp } from '@inertiajs/react'
   import { ToastProvider, Toasts } from '@laravel-inertia-toast/react'
   
   createInertiaApp({
     resolve: (name) => {
       const pages = import.meta.glob('./Pages/**/*.tsx', { eager: true })
       return pages[`./Pages/${name}.tsx`]
     },
     setup({ el, App, props }) {
       createRoot(el).render(
         <ToastProvider>
           <App {...props} />
   
   		<Toasts />
         </ToastProvider>
       )
     },
   })
   

   The ToastProvider automatically listens to Inertia’s flash event and displays toasts from your Laravel backend.

2. Configure the provider (optional)

   You can customize the default behavior by passing a config prop:

   <ToastProvider
     config={{
       duration: 5000,
       position: 'top-right',
       maxVisible: 5,
       propKey: 'toasts',
     }}
   >
     <App {...props} />
   </ToastProvider>
   

   Configuration options

   Option	Type	Default	Description
   duration	number	5000	Default duration in milliseconds before toasts auto-dismiss
   position	string	'top-right'	Toast position: 'top-right', 'top-left', 'top-center', 'bottom-right', 'bottom-left', 'bottom-center'
   maxVisible	number	5	Maximum number of toasts visible at once
   propKey	string	'toasts'	The flash key used in Laravel responses

Using the hook

The useToast hook provides methods to programmatically create toasts from your React components.

Basic usage

import { useToast } from '@laravel-inertia-toast/react'

export default function MyComponent() {
  const toast = useToast()

  function handleSuccess() {
    toast.success('Operation completed successfully!')
  }

  function handleError() {
    toast.error('Something went wrong!')
  }

  return (
    <div>
      <button onClick={handleSuccess}>Show Success</button>
      <button onClick={handleError}>Show Error</button>
    </div>
  )
}

Available methods

The useToast hook returns an object with the following methods:

success(message, options?)

Displays a success toast.

toast.success('Your changes have been saved!')

// With options
toast.success('Profile updated!', {
  title: 'Success',
  duration: 3000,
})

error(message, options?)

Displays an error toast.

toast.error('Failed to save changes')

// With options
toast.error('Invalid credentials', {
  title: 'Authentication Error',
  duration: 7000,
})

info(message, options?)

Displays an info toast.

toast.info('New features are available')

// With options
toast.info('Check your email for verification', {
  title: 'Info',
  duration: 4000,
})

warning(message, options?)

Displays a warning toast.

toast.warning('Your session will expire soon')

// With options
toast.warning('Unsaved changes detected', {
  title: 'Warning',
  duration: 6000,
})

Toast options

You can customize individual toasts using the options parameter:

interface ToastOptions {
  title?: string       // Optional title displayed above the message
  duration?: number    // Custom duration in milliseconds (overrides default)
}

TypeScript support

The package is written in TypeScript and includes full type definitions:

import type {
  ToastLevel,
  ToastMessage,
  ToastItemType,
  ToastConfig,
  ToastProviderProps,
  ToastContextValue,
  ToastOptions,
} from '@laravel-inertia-toast/react'

// Toast levels
type ToastLevel = 'success' | 'error' | 'info' | 'warning'

// Toast message structure
interface ToastMessage {
  message: string
  level: ToastLevel
  title: string | null
  duration: number | null
}

// Toast item with ID
interface ToastItemType extends ToastMessage {
  id: string
}

// Configuration options
interface ToastConfig {
  duration: number
  position: string
  maxVisible: number
  propKey: string
}

// Provider props
interface ToastProviderProps {
  children: React.ReactNode
  config?: Partial<ToastConfig>
}

// Hook return value
interface ToastContextValue {
  items: ToastItemType[]
  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
}

Advanced usage

Custom toast wrapper

You can create a custom wrapper component with predefined settings:

import { useToast } from '@lombacode/laravel-inertia-toast-react'

export function useNotifications() {
  const toast = useToast()

  return {
    success: (message: string) =>
      toast.success(message, {
        title: 'Success',
        duration: 3000,
      }),
    error: (message: string) =>
      toast.error(message, {
        title: 'Error',
        duration: 7000,
      }),
    notify: (message: string) =>
      toast.info(message, {
        title: 'Notification',
        duration: 5000,
      }),
  }
}

// Usage in components
export default function MyComponent() {
  const notifications = useNotifications()

  return (
    <button onClick={() => notifications.success('Task completed!')}>Complete Task</button>
  )
}

Context access

For advanced use cases, you can access the ToastContext directly:

import { useContext } from 'react'
import { ToastContext } from '@laravel-inertia-toast/react'

export default function AdvancedComponent() {
  const context = useContext(ToastContext)

  if (!context) {
    throw new Error('Must be used within ToastProvider')
  }

  // Use context.items, context.config, etc.
  return <div>Active toasts: {context.items.length}</div>
}

Direct context access is for advanced use cases. It is unnecessary and highly discouraged. Use the useToast hook for most scenarios.

Next steps

Styling

Customize the appearance of your toasts

Laravel setup

Configure Laravel to send toast notifications