Quickstart

Get your first toast notification working in minutes

This guide will help you create your first toast notification. We’ll cover both server-side (PHP) and client-side (Vue/React) usage.

Make sure you’ve completed the installation steps before continuing.

Server-side toast (from PHP)

The most common use case is showing a toast after a form submission or action in your Laravel controller.

1. Use the Toast facade in your controller

   <?php
   
   namespace App\Http\Controllers;
   
   use Illuminate\Http\Request;
   use InertiaToast\Facades\Toast;
   
   class ProfileController extends Controller
   {
       public function update(Request $request)
       {
           // Validate and update the user's profile
           $request->user()->update([
               'name' => $request->name,
               'email' => $request->email,
           ]);
   
           // Show a success toast
           Toast::success('Profile updated successfully!');
   
           return redirect()->route('profile.show');
       }
   }
   

   The toast will automatically appear on the next page after the redirect.

2. Try different toast types

   Laravel Inertia Toast supports four types of toasts:

   use InertiaToast\Facades\Toast;
   
   // Success toast (green)
   Toast::success('Operation completed successfully!');
   
   // Error toast (red)
   Toast::error('Something went wrong. Please try again.');
   
   // Info toast (blue)
   Toast::info('Check your email for a confirmation link.');
   
   // Warning toast (yellow)
   Toast::warning('Your subscription is about to expire.');
   
3. Add optional titles

   You can add a title to provide more context:

   // Using named arguments
   Toast::success('Your changes have been saved.', title: 'Success');
   
   Toast::error('Failed to delete the item.', title: 'Error');
   

Client-side toast (from Vue/React)

You can also trigger toasts from your frontend components using the useToast() composable/hook.

Vue 3

1. Import and use the composable

   <script setup>
   import { useToast } from '@laravel-inertia-toast/vue'
   
   const { success, error, info, warning } = useToast()
   
   function copyToClipboard() {
     navigator.clipboard.writeText('Hello, World!')
     success('Copied to clipboard!')
   }
   
   function handleError() {
     error('Failed to copy to clipboard.')
   }
   </script>
   
   <template>
     <div>
       <button @click="copyToClipboard">
         Copy Text
       </button>
       <button @click="handleError">
         Trigger Error
       </button>
     </div>
   </template>
   
2. Add titles and custom duration

   Pass an options object as the second argument:

   <script setup>
   import { useToast } from '@laravel-inertia-toast/vue'
   
   const { success, error } = useToast()
   
   function deleteItem() {
     // Simulate deletion
     setTimeout(() => {
       success('Item has been removed from your cart.', {
         title: 'Deleted',
         duration: 3000, // Auto-dismiss after 3 seconds
       })
     }, 500)
   }
   
   function handleSlowAction() {
     info('Processing your request...', {
       duration: 10000, // Show for 10 seconds
     })
   }
   </script>
   
   <template>
     <div>
       <button @click="deleteItem">Delete Item</button>
       <button @click="handleSlowAction">Slow Action</button>
     </div>
   </template>
   

React

1. Import and use the hook

   import { useToast } from '@laravel-inertia-toast/react'
   
   export default function MyComponent() {
     const { success, error, info, warning } = useToast()
   
     const copyToClipboard = () => {
       navigator.clipboard.writeText('Hello, World!')
       success('Copied to clipboard!')
     }
   
     const handleError = () => {
       error('Failed to copy to clipboard.')
     }
   
     return (
       <div>
         <button onClick={copyToClipboard}>
           Copy Text
         </button>
         <button onClick={handleError}>
           Trigger Error
         </button>
       </div>
     )
   }
   
2. Add titles and custom duration

   Pass an options object as the second argument:

   import { useToast } from '@laravel-inertia-toast/react'
   
   export default function MyComponent() {
     const { success, info } = useToast()
   
     const deleteItem = () => {
       // Simulate deletion
       setTimeout(() => {
         success('Item has been removed from your cart.', {
           title: 'Deleted',
           duration: 3000, // Auto-dismiss after 3 seconds
         })
       }, 500)
     }
   
     const handleSlowAction = () => {
       info('Processing your request...', {
         duration: 10000, // Show for 10 seconds
       })
     }
   
     return (
       <div>
         <button onClick={deleteItem}>Delete Item</button>
         <button onClick={handleSlowAction}>Slow Action</button>
       </div>
     )
   }
   

Using the helper function

The toast() helper provides a fluent alternative to the facade:

// Fluent builder pattern
toast('Profile updated!')->success();
toast('Something went wrong.')->error();
toast('Slow message.')->duration(10000)->warning();

// Add title
toast('Item has been removed.')
    ->title('Deleted')
    ->error();

// Chain multiple options
toast('Your session is about to expire.')
    ->title('Warning')
    ->duration(10000)
    ->warning();

// Direct access to Toaster (shorthand)
toast()->success('Quick shorthand');

Complete example

Here’s a complete example showing a form submission with validation and toast notifications:

Controller (PHP)

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use Illuminate\Http\Request;
use InertiaToast\Facades\Toast;

class PostController extends Controller
{
    public function store(Request $request)
    {
        $validated = $request->validate([
            'title' => 'required|max:255',
            'content' => 'required',
        ]);

        try {
            $post = Post::create([
                'title' => $validated['title'],
                'content' => $validated['content'],
                'user_id' => $request->user()->id,
            ]);

            Toast::success('Your post has been published!', title: 'Success');

            return redirect()->route('posts.show', $post);
        } catch (\Exception $e) {
            Toast::error('Failed to create post. Please try again.', title: 'Error');

            return back();
        }
    }

    public function destroy(Post $post)
    {
        $this->authorize('delete', $post);

        $post->delete();

        toast('Post has been deleted.')
            ->title('Deleted')
            ->duration(3000)
            ->success();

        return redirect()->route('posts.index');
    }
}

Component (Vue)

<script setup>
import { ref } from 'vue'
import { router } from '@inertiajs/vue3'
import { useToast } from '@laravel-inertia-toast/vue'

const { success, error } = useToast()
const copying = ref(false)

const props = defineProps({
  post: Object,
})

function sharePost() {
  const url = window.location.href
  
  navigator.clipboard.writeText(url)
    .then(() => {
      success('Link copied to clipboard!', {
        title: 'Shared',
      })
    })
    .catch(() => {
      error('Failed to copy link.', {
        title: 'Error',
      })
    })
}

function deletePost() {
  if (!confirm('Are you sure you want to delete this post?')) {
    return
  }

  router.delete(`/posts/${props.post.id}`, {
    onError: () => {
      error('Failed to delete post.')
    },
  })
}
</script>

<template>
  <div>
    <h1>{{ post.title }}</h1>
    <div v-html="post.content" />
    
    <div class="mt-4 space-x-2">
      <button @click="sharePost">
        Share
      </button>
      <button @click="deletePost">
        Delete
      </button>
    </div>
  </div>
</template>

Component (React)

import { router } from '@inertiajs/react'
import { useToast } from '@laravel-inertia-toast/react'

interface Post {
  id: number
  title: string
  content: string
}

interface Props {
  post: Post
}

export default function ShowPost({ post }: Props) {
  const { success, error } = useToast()

  const sharePost = () => {
    const url = window.location.href
    
    navigator.clipboard.writeText(url)
      .then(() => {
        success('Link copied to clipboard!', {
          title: 'Shared',
        })
      })
      .catch(() => {
        error('Failed to copy link.', {
          title: 'Error',
        })
      })
  }

  const deletePost = () => {
    if (!confirm('Are you sure you want to delete this post?')) {
      return
    }

    router.delete(`/posts/${post.id}`, {
      onError: () => {
        error('Failed to delete post.')
      },
    })
  }

  return (
    <div>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
      
      <div className="mt-4 space-x-2">
        <button onClick={sharePost}>
          Share
        </button>
        <button onClick={deletePost}>
          Delete
        </button>
      </div>
    </div>
  )
}

Next steps

Now that you have your first toast working, explore more advanced features:

Server-side usage

Learn more about using the PHP API

Client-side usage

Explore Vue and React APIs

Configuration

Customize toast behavior and appearance

TypeScript support

Full type definitions and interfaces