Vue 3

Set up Laravel Inertia Toast with Vue 3

Learn how to integrate Laravel Inertia Toast with Vue 3. This guide covers plugin installation, component setup, and usage of the useToast composable.

Installation

First, install the Vue 3 package:

npm install @laravel-inertia-toast/vue

Setup

1. Register the plugin

   You can customize the default behavior by passing configuration options:

   import { InertiaToast } from '@laravel-inertia-toast/vue'
   
   createApp({ render: () => h(App, props) })
     .use(plugin)
     .use(InertiaToast, {
       duration: 5000,
       position: 'top-right',
       maxVisible: 5,
       propKey: 'toasts',
     })
     .mount(el)
   

   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

2. Add the Toasts component

   Place the <Toasts /> component in your root layout file (e.g., Layout.vue):

   <script setup lang="ts">
   import { Link } from '@inertiajs/vue3'
   import { Toasts } from '@laravel-inertia-toast/vue'
   </script>
   
   <template>
     <div>
       <header>
         {/*  Your header content  */}
       </header>
   
       <main>
         <slot />
       </main>
   
       <Toasts />
     </div>
   </template>
   

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

Using the composable

The useToast composable provides methods to programmatically create toasts from your Vue components.

Basic usage

<script setup lang="ts">
import { useToast } from '@laravel-inertia-toast/vue'

const toast = useToast()

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

function handleError() {
  toast.error('Something went wrong!')
}
</script>

<template>
  <div>
    <button @click="handleSuccess">Show Success</button>
    <button @click="handleError">Show Error</button>
  </div>
</template>

Available methods

The useToast composable 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,
  InertiaToastOptions,
} from '@laravel-inertia-toast/vue'

// 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
}

Advanced usage

Direct store access

For advanced use cases, you can access the toast store directly:

import { toastStore } from '@laravel-inertia-toast/vue'

// Add a toast
toastStore.addToast({
  message: 'Custom toast',
  level: 'info',
  title: null,
  duration: null,
})

// Remove a toast
toastStore.removeToast('toast-1-1234567890')

// Clear all toasts
toastStore.clearToasts()

// Update configuration
toastStore.configure({
  duration: 7000,
  position: 'bottom-right',
})

Direct store manipulation is for advanced use cases. It is unnecessary and highly discouraged. Use the useToast composable for most scenarios.

Next steps

Styling

Customize the appearance of your toasts

Laravel setup

Configure Laravel to send toast notifications