Skip to main content
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 @lombacode/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 } from '@lombacode/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} />
      </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

OptionTypeDefaultDescription
durationnumber5000Default duration in milliseconds before toasts auto-dismiss
positionstring'top-right'Toast position: 'top-right', 'top-left', 'top-center', 'bottom-right', 'bottom-left', 'bottom-center'
maxVisiblenumber5Maximum number of toasts visible at once
propKeystring'toasts'The flash key used in Laravel responses
3

Add the Toasts component

Place the <Toasts /> component in your root layout file (e.g., Layout.tsx):
import { Link } from '@inertiajs/react'
import { Toasts } from '@lombacode/laravel-inertia-toast-react'

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <div>
      <header>
        {/* Your header content */}
      </header>

      <main>{children}</main>

      <Toasts />
    </div>
  )
}
The <Toasts /> component uses a fixed position, so it doesn’t matter where in your layout you place it.

​
Using the hook

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

​
Basic usage

import { useToast } from '@lombacode/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>
  )
}
The useToast hook must be used within a component that is wrapped by <ToastProvider>. Otherwise, it will throw an error.

​
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,
})

​
remove(id)

Removes a specific toast by its ID. 
toast.remove('toast-1-1234567890')

​
clear()

Removes all active toasts. 
toast.clear()

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

​
Accessing toast state

The hook also provides access to the current toast state: 
import { useToast } from '@lombacode/laravel-inertia-toast-react'

export default function ToastDebugger() {
  const { items, config } = useToast()

  return (
    <div>
      <h2>Active Toasts: {items.length}</h2>
      <pre>{JSON.stringify(config, null, 2)}</pre>
    </div>
  )
}

​
TypeScript support

The package is written in TypeScript and includes full type definitions: 
import type {
  ToastLevel,
  ToastMessage,
  ToastItemType,
  ToastConfig,
  ToastProviderProps,
  ToastContextValue,
  ToastOptions,
} from '@lombacode/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. Use the useToast hook for most scenarios.

​
Next steps

Styling

Customize the appearance of your toasts

Laravel setup

Configure Laravel to send toast notifications

Build docs developers (and LLMs) love

Get started for freeTalk to us