Client-side usage

Trigger toast notifications from your Vue or React components using the useToast composable/hook

You can trigger toast notifications directly from your frontend components using the useToast() composable (Vue) or hook (React). This is useful for client-side interactions like copy-to-clipboard, form submissions, or any action that doesn’t require a server round-trip.

Vue 3

The useToast composable returns methods for triggering toasts:

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

const { success, error, info, warning } = useToast()

function handleCopy() {
  navigator.clipboard.writeText('some text')
  success('Copied to clipboard!')
}

function handleDelete() {
  // Perform deletion
  error('Item has been removed.', { title: 'Deleted' })
}
</script>

<template>
  <div>
    <button @click="handleCopy">Copy</button>
    <button @click="handleDelete">Delete</button>
  </div>
</template>

Return value

The useToast() composable returns:

{
  items: ComputedRef<ToastItem[]>,
  config: ComputedRef<ToastConfig>,
  success: (message: string, options?: { title?: string; duration?: number }) => void,
  error: (message: string, options?: { title?: string; duration?: number }) => void,
  info: (message: string, options?: { title?: string; duration?: number }) => void,
  warning: (message: string, options?: { title?: string; duration?: number }) => void,
  remove: (id: string) => void,
  clear: () => void
}

React

The useToast hook returns the same methods for triggering toasts:

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

function MyComponent() {
  const { success, error, info, warning } = useToast()

  function handleCopy() {
    navigator.clipboard.writeText('some text')
    success('Copied to clipboard!')
  }

  function handleDelete() {
    // Perform deletion
    error('Item has been removed.', { title: 'Deleted' })
  }

  return (
    <div>
      <button onClick={handleCopy}>Copy</button>
      <button onClick={handleDelete}>Delete</button>
    </div>
  )
}

The useToast hook must be used within a <ToastProvider> component. If you try to use it outside the provider, you’ll get an error. We recommend wrapping your whole app with the <ToastProvider>.

Return value

The useToast() hook returns:

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

Toast methods

All four toast methods share the same signature:

(message: string, options?: { title?: string; duration?: number }) => void

Success toasts

Use for successful operations:

Vue

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

const { success } = useToast()

function handleSubmit() {
  // Submit form
  success('Form submitted successfully!')
}
</script>

React

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

function FormComponent() {
  const { success } = useToast()

  function handleSubmit() {
    // Submit form
    success('Form submitted successfully!')
  }

  return <button onClick={handleSubmit}>Submit</button>
}

Error toasts

Use for errors and failures:

Vue

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

const { error } = useToast()

async function handleRequest() {
  try {
    await fetchData()
  } catch (err) {
    error('Failed to load data', { title: 'Error' })
  }
}
</script>

React

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

function DataComponent() {
  const { error } = useToast()

  async function handleRequest() {
    try {
      await fetchData()
    } catch (err) {
      error('Failed to load data', { title: 'Error' })
    }
  }

  return <button onClick={handleRequest}>Load</button>
}

Info toasts

Use for informational messages:

Vue

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

const { info } = useToast()

function showTip() {
  info('Press Ctrl+K to open command palette')
}
</script>

React

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

function TipButton() {
  const { info } = useToast()

  return (
    <button onClick={() => info('Press Ctrl+K to open command palette')}>
      Show Tip
    </button>
  )
}

Warning toasts

Use for warnings:

Vue

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

const { warning } = useToast()

function checkStorage() {
  if (isStorageLow()) {
    warning('Storage space is running low', { title: 'Warning' })
  }
}
</script>

React

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

function StorageCheck() {
  const { warning } = useToast()

  function checkStorage() {
    if (isStorageLow()) {
      warning('Storage space is running low', { title: 'Warning' })
    }
  }

  return <button onClick={checkStorage}>Check Storage</button>
}

Options

All toast methods accept an optional second parameter with the following options:

Title

Add a title to provide context:

Vue

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

const { success } = useToast()

success('Your changes have been saved.', { title: 'Success' })
</script>

React

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

function Component() {
  const { success } = useToast()

  success('Your changes have been saved.', { title: 'Success' })
}

Duration

Override the default auto-dismiss duration (in milliseconds):

Vue

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

const { info } = useToast()

// Show for 10 seconds
info('This is a longer message.', { duration: 10000 })
</script>

React

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

function Component() {
  const { info } = useToast()

  // Show for 10 seconds
  info('This is a longer message.', { duration: 10000 })
}

Combining options

Vue

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

const { warning } = useToast()

warning('Your session will expire soon.', {
  title: 'Session Warning',
  duration: 15000
})
</script>

React

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

function Component() {
  const { warning } = useToast()

  warning('Your session will expire soon.', {
    title: 'Session Warning',
    duration: 15000
  })
}

Managing toasts

Remove a specific toast

You can manually dismiss a toast using its ID:

Vue

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

const { items, remove } = useToast()

function removeFirstToast() {
  if (items.value.length > 0) {
    remove(items.value[0].id)
  }
}
</script>

React

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

function Component() {
  const { items, remove } = useToast()

  function removeFirstToast() {
    if (items.length > 0) {
      remove(items[0].id)
    }
  }

  return <button onClick={removeFirstToast}>Remove First</button>
}

Clear all toasts

Dismiss all visible toasts at once:

Vue

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

const { clear } = useToast()
</script>

<template>
  <button @click="clear">Clear All</button>
</template>

React

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

function ClearButton() {
  const { clear } = useToast()

  return <button onClick={clear}>Clear All</button>
}

Accessing toast state

You can access the current toast items and configuration:

Vue

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

const { items, config } = useToast()

// items is a ComputedRef<ToastItem[]>
// config is a ComputedRef<ToastConfig>
</script>

<template>
  <div>Active toasts: {{ items.length }}</div>
  <div>Position: {{ config.position }}</div>
</template>

React

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

function ToastInfo() {
  const { items, config } = useToast()

  return (
    <div>
      <div>Active toasts: {items.length}</div>
      <div>Position: {config.position}</div>
    </div>
  )
}

TypeScript types

ToastItem

interface ToastItem {
  id: string
  message: string
  level: 'success' | 'error' | 'info' | 'warning'
  title: string | null
  duration: number | null
}

ToastConfig

interface ToastConfig {
  duration: number        // Default duration in milliseconds
  position: string        // Toast position on screen
  maxVisible: number      // Maximum number of visible toasts
  propKey: string         // Inertia flash key
}

ToastOptions

interface ToastOptions {
  title?: string          // Optional toast title
  duration?: number       // Optional custom duration in milliseconds
}

Common patterns

Copy to clipboard

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

const { success, error } = useToast()

async function copyToClipboard(text: string) {
  try {
    await navigator.clipboard.writeText(text)
    success('Copied to clipboard!')
  } catch (err) {
    error('Failed to copy', { title: 'Error' })
  }
}
</script>