ToastProvider

Context provider that enables toast notifications in your React application

The ToastProvider component wraps your application and provides toast functionality to all child components. It automatically listens for flash messages from Inertia.js and manages the toast state.

Setup

Wrap your application with the ToastProvider component, typically in your root layout:

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

export default function Layout({ children }) {
  return (
    <ToastProvider>
      {children}
      <Toasts />
    </ToastProvider>
  )
}

Props

children · React.ReactNode · required

The React components to render inside the provider. This is typically your entire application or layout.

config · Partial<ToastConfig>

Optional configuration object to customize toast behavior and appearance.

config.duration · number · default: "5000"

Default duration in milliseconds that toasts remain visible. Set to 0 to disable auto-dismiss.

config.position · string · default: "top-right"

Default position where toasts appear on screen.

Options:

• top-right
• top-left
• top-center
• bottom-right
• bottom-left
• bottom-center

config.maxVisible · number · default: "5"

Maximum number of toasts that can be displayed simultaneously. Older toasts are automatically removed when this limit is exceeded.

config.propKey · string · default: "toasts"

The key name used to read toast data from Inertia flash messages. This should match the key used in your Laravel backend.

Configuration examples

Custom position and duration

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

export default function Layout({ children }) {
  return (
    <ToastProvider
      config={{
        position: 'bottom-right',
        duration: 3000,
      }}
    >
      {children}
      <Toasts />
    </ToastProvider>
  )
}

Disable auto-dismiss

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

export default function Layout({ children }) {
  return (
    <ToastProvider
      config={{
        duration: 0, // Toasts stay visible until manually dismissed
      }}
    >
      {children}
      <Toasts />
    </ToastProvider>
  )
}

Custom flash message key

If you’re using a custom key in your Laravel backend:

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

export default function Layout({ children }) {
  return (
    <ToastProvider
      config={{
        propKey: 'notifications', // Match your Laravel configuration
      }}
    >
      {children}
      <Toasts />
    </ToastProvider>
  )
}

Limit visible toasts

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

export default function Layout({ children }) {
  return (
    <ToastProvider
      config={{
        maxVisible: 3, // Only show 3 toasts at a time
      }}
    >
      {children}
      <Toasts />
    </ToastProvider>
  )
}

Context value

The ToastProvider creates a context that provides the following values to child components via the useToast hook:

items · ToastItem[]

Array of currently active toast items.

config · ToastConfig

The merged configuration object combining defaults and user-provided overrides.

success · (message: string, options?: ToastOptions) => void

Function to display a success toast.

error · (message: string, options?: ToastOptions) => void

Function to display an error toast.

info · (message: string, options?: ToastOptions) => void

Function to display an info toast.

warning · (message: string, options?: ToastOptions) => void

Function to display a warning toast.

remove · (id: string) => void

Function to remove a specific toast by its ID.

clear · () => void

Function to remove all active toasts.

TypeScript types

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

interface ToastConfig {
  duration: number
  position: string
  maxVisible: number
  propKey: string
}

interface ToastOptions {
  title?: string
  duration?: number
}

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
}

The ToastProvider automatically listens for Inertia.js flash messages and displays them as toasts. Make sure your Laravel backend is configured to send toast data in the flash session.