Components

UI components for rendering toast notifications

The React package provides two main components for rendering toasts: Toasts (the container) and ToastItem (individual toast).

Toasts

The Toasts component is a container that renders all active toast notifications. It should be placed once in your application layout.

Usage

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

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

Props

The Toasts component accepts no props. It automatically retrieves toast items and configuration from the ToastProvider context.

Behavior

• Automatically positions toasts based on the position config from ToastProvider
• Renders toasts with proper ARIA attributes for accessibility (aria-live="polite")
• Applies responsive styling with a maximum width of sm (24rem)
• Stacks multiple toasts with vertical spacing

Position mapping

The component maps position config values to CSS classes:

Position	CSS Classes
top-right	top-4 right-4 items-end
top-left	top-4 left-4 items-start
top-center	top-4 left-1/2 -translate-x-1/2 items-center
bottom-right	bottom-4 right-4 items-end
bottom-left	bottom-4 left-4 items-start
bottom-center	bottom-4 left-1/2 -translate-x-1/2 items-center

ToastItem

The ToastItem component renders an individual toast notification with animations, icons, and a dismiss button.

You typically don’t need to use ToastItem directly. The Toasts component automatically renders it for each active toast.

Props

toast · ToastItem · required

The toast item data to render.

toast.id · string · required

Unique identifier for the toast (auto-generated).

toast.message · string · required

The main message content to display.

toast.level · ToastLevel · required

The severity level of the toast. Determines the icon and color scheme.

Options: success | error | info | warning

toast.title · string | null

Optional title displayed above the message in bold.

toast.duration · number | null

Optional override for the auto-dismiss duration. Uses config default if null.

config · ToastConfig · required

The global toast configuration from the provider.

position · string · required

The position where toasts are displayed. Used to determine animation direction.

onRemove · (id: string) => void · required

Callback function invoked when the toast should be removed from state.

Features

Animations

• Enter animation: Fades in and slides from the edge over 300ms
• Exit animation: Fades out and slides back to the edge over 200ms
• Animation direction automatically adjusts based on position:
  • Right positions: slides from/to right
  • Left positions: slides from/to left
  • Top positions: slides from/to top
  • Bottom positions: slides from/to bottom

Icons

Each toast level displays a distinct icon with matching colors:

Level	Icon	Background	Text Color
success	Checkmark circle	bg-green-100	text-green-500
error	X circle	bg-rose-100	text-rose-500
warning	Warning triangle	bg-yellow-100	text-yellow-500
info	Info circle	bg-blue-100	text-blue-500

Auto-dismiss

• Toasts automatically dismiss after the configured duration
• Duration can be overridden per-toast via the duration property
• Set duration to 0 to disable auto-dismiss for specific toasts
• Timer is cleared if the toast is manually dismissed

Dismiss button

• Every toast includes a close button in the top-right corner
• Clicking triggers the exit animation and removes the toast
• Accessible with proper ARIA labels and focus states

TypeScript types

type ToastLevel = 'success' | 'error' | 'info' | 'warning'

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 ToastItemProps {
  toast: ToastItem
  config: ToastConfig
  position: string
  onRemove: (id: string) => void
}

Custom usage example

If you need to render a ToastItem directly (advanced use case):

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

function CustomToastContainer() {
  const { items, config, remove } = useToast()
  
  return (
    <div className="custom-container">
      {items.map((item) => (
        <ToastItem
          key={item.id}
          toast={item}
          config={config}
          position={config.position}
          onRemove={remove}
        />
      ))}
    </div>
  )
}

Styling

Both components use Tailwind CSS classes for styling. The default theme provides:

• White background with subtle shadow
• Rounded corners (rounded-lg)
• Responsive padding
• Smooth transitions and animations
• Accessible color contrast ratios
• Hover and focus states for interactive elements

To customize the appearance, you can:

1. Override Tailwind classes in your global CSS
2. Fork the component and modify the class names
3. Use Tailwind’s JIT mode to extend the default theme