Installation

Install and configure Laravel Inertia Toast for your Laravel + Inertia.js application

Laravel Inertia Toast consists of three packages: a PHP backend package and two frontend adapters (Vue 3 and React). You need to install the PHP package and the adapter for your frontend framework.

Installation

1. Install the PHP package

   Install the Laravel package via Composer:

   composer require veekthoven/laravel-inertia-toast
   

   The service provider and facade are automatically registered via Laravel’s package discovery.

   Optionally, publish the configuration file:

   php artisan vendor:publish --tag=inertia-toast-config
   

   This creates a config/inertia-toast.php file where you can customize default settings.

2. Install the frontend adapter

   Choose the adapter for your frontend framework:

   npm (Vue 3)

   npm install @laravel-inertia-toast/vue
   
3. Configure your frontend

   Set up the toast components in your application.

   Vue 3

   Register the plugin in your resources/js/app.js:

   import { createApp, h } from 'vue'
   import { createInertiaApp } from '@inertiajs/vue3'
   import { InertiaToast } from '@laravel-inertia-toast/vue'
   
   createinertiaApp({
   	resolve: (name) => {
   		const pages = import.meta.glob('./Pages/**/*.vue', { eager: true })
   		return pages[`./Pages/${name}.vue`]
   	},
   	setup({ el, App, props, plugin }) {
   		createApp({ render: () => h(App, props) })
   			.use(plugin)
   			.use(InertiaToast, {
   				duration: 5000,
   				position: 'top-right',
   				maxVisible: 5,
   			})
   			.mount(el)
   	},
   })
   

   Add the <Toasts /> component to your main layout file:

   <script setup>
   	import { Toasts } from '@laravel-inertia-toast/vue'
   </script>
   
   <template>
   	<div>
   		{/*  Your layout content  */}
   		<slot />
   
   		{/*  Toast container  */}
   		<Toasts />
   	</div>
   </template>
   

   React

   Wrap your app with <ToastProvider> in your resources/js/app.tsx:

   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 }) {
   const root = createRoot(el)
   
   root.render(
   <ToastProvider
   config={{
     position: 'top-right',
     duration: 5000,
     maxVisible: 5,
   }}
   >
   <App {...props} />
   <Toasts />
   </ToastProvider>
   )
   },
   })
   

   The <Toasts /> component can be placed inside <ToastProvider> anywhere in your app. Many developers prefer adding it to the main app setup as shown above.

4. Configure Tailwind CSS

   Since the toast components use Tailwind classes internally, you need to add the package to Tailwind’s source detection so the required classes are generated.

   Tailwind v4

   Add the following @source directive to your main CSS file (e.g., resources/css/app.css):

   Vue 3

   @import "tailwindcss";
   
   @source "../../node_modules/@laravel-inertia-toast/vue/dist/**/*.js";
   

   The relative path above assumes your CSS file is at resources/css/app.css. Adjust accordingly if your setup differs.

   Tailwind v3

   Add the package path to the content array in your tailwind.config.js:

   Vue 3

   /** @type {import('tailwindcss').Config} */
   export default {
     content: [
       './vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php',
       './storage/framework/views/*.php',
       './resources/**/*.blade.php',
       './resources/**/*.js',
       './resources/**/*.vue',
       './node_modules/@laravel-inertia-toast/vue/dist/**/*.js',
     ],
     theme: {
       extend: {},
     },
     plugins: [],
   }
   

Configuration options

Both the PHP backend and frontend adapters support configuration options:

PHP configuration

Publish the config file to customize default settings:

php artisan vendor:publish --tag=inertia-toast-config

This creates config/inertia-toast.php:

return [
    // Default duration (in milliseconds) before a toast auto-dismisses
    'duration' => 5000,

    // Where toasts appear on screen
    // Options: top-right, top-left, top-center, bottom-right, bottom-left, bottom-center
    'position' => 'top-right',

    // Maximum number of toasts visible at once
    'max_visible' => 5,

    // The key used when flashing toast data via Inertia::flash()
    'prop_key' => 'toasts',
];

Frontend configuration

You can override the backend defaults when registering the plugin or provider:

Vue 3

app.use(InertiaToast, {
  duration: 3000,        // Auto-dismiss after 3 seconds
  position: 'top-center', // Show toasts at top-center
  maxVisible: 3,          // Show max 3 toasts at once
  propKey: 'toasts',      // Inertia flash key (must match backend)
})

React

<ToastProvider
  config={{
    duration: 3000,        // Auto-dismiss after 3 seconds
    position: 'top-center', // Show toasts at top-center
    maxVisible: 3,          // Show max 3 toasts at once
    propKey: 'toasts',      // Inertia flash key (must match backend)
  }}
>
  {/* ... */}
</ToastProvider>

If you change prop_key in the PHP config, make sure to update propKey in your frontend configuration to match.

Next steps

Quickstart

Create your first toast notification

Server-side usage

Learn about the PHP API