Customization

Customize toast appearance, duration, and behavior to match your application’s needs

Laravel Inertia Toast provides flexible configuration options to customize the appearance and behavior of your toasts.

Duration settings

Control how long toasts remain visible before automatically dismissing.

Default duration

Set the default duration for all toasts in your application.

PHP (Backend)

Configure the default duration in the config file:

config/inertia-toast.php

return [
    'duration' => 5000, // 5 seconds (in milliseconds)
    'position' => 'top-right',
    'max_visible' => 5,
    'prop_key' => 'toasts',
];

Vue 3 (Frontend)

Set the duration when registering the plugin:

resources/js/app.js

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

const app = createApp(App)
app.use(InertiaToast, {
    duration: 5000, // 5 seconds
    position: 'top-right',
    maxVisible: 5,
})
app.mount('#app')

React (Frontend)

Set the duration in the ToastProvider config:

resources/js/app.tsx

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

<ToastProvider
    config={{
        duration: 5000, // 5 seconds
        position: 'top-right',
        maxVisible: 5,
    }}
>
    <App {...props} />
    <Toasts />
</ToastProvider>

Per-toast duration

Override the default duration for individual toasts.

PHP Facade

use InertiaToast\Facades\Toast;

// Quick notification (3 seconds)
Toast::success('Saved!', duration: 3000);

// Important warning (10 seconds)
Toast::warning('Your session is about to expire.', duration: 10000);

// With title and custom duration
Toast::error(
    'Failed to process payment.',
    title: 'Payment Error',
    duration: 8000
);

PHP Helper

// Using the fluent helper
toast('Quick message')->duration(3000)->success();

toast('Read this carefully')
    ->duration(10000)
    ->warning();

toast('Operation failed')
    ->title('Error')
    ->duration(8000)
    ->error();

Vue 3

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

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

function handleCopy() {
  success('Copied to clipboard!', { duration: 2000 })
}

function handleWarning() {
  warning('Your session is about to expire.', {
    title: 'Warning',
    duration: 10000
  })
}
</script>

React

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

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

  const handleCopy = () => {
    success('Copied to clipboard!', { duration: 2000 })
  }

  const handleWarning = () => {
    warning('Your session is about to expire.', {
      title: 'Warning',
      duration: 10000
    })
  }

  return (
    <>
      <button onClick={handleCopy}>Copy</button>
      <button onClick={handleWarning}>Show Warning</button>
    </>
  )
}

Duration is specified in milliseconds. For example, 3000 = 3 seconds, 5000 = 5 seconds, 10000 = 10 seconds.

Max visible toasts

Limit the number of toasts that can be displayed simultaneously on screen.

PHP (Backend)

config/inertia-toast.php

return [
    'duration' => 5000,
    'position' => 'top-right',
    'max_visible' => 5, // Maximum 5 toasts at once
    'prop_key' => 'toasts',
];

Vue 3 (Frontend)

resources/js/app.js

app.use(InertiaToast, {
    duration: 5000,
    position: 'top-right',
    maxVisible: 5, // Maximum 5 toasts at once
})

React (Frontend)

resources/js/app.tsx

<ToastProvider
    config={{
        duration: 5000,
        position: 'top-right',
        maxVisible: 5, // Maximum 5 toasts at once
    }}
>
    <App {...props} />
    <Toasts />
</ToastProvider>

When the maximum is reached, the oldest toast is automatically removed to make room for new ones.

A good range for maxVisible is between 3-5 toasts. Too many toasts can overwhelm users and clutter the interface.

Inertia flash key

Customize the key used for flashing toast data through Inertia.js.

config/inertia-toast.php

return [
    'duration' => 5000,
    'position' => 'top-right',
    'max_visible' => 5,
    'prop_key' => 'toasts', // Change this if it conflicts with your app
];

The prop_key setting determines the Inertia flash key name. You typically only need to change this if:

• You already use a prop named toasts in your Inertia shared data
• You want to namespace the toast data differently
• You’re integrating with an existing notification system

If you change the prop_key, make sure it doesn’t conflict with other Inertia shared props in your application.

Configuration hierarchy

When the same setting is configured in multiple places, the following priority order applies:

1. Per-toast options (highest priority) - Toast::success('...', duration: 3000)
2. Frontend configuration - Plugin/Provider config in app.js/app.tsx
3. Backend configuration (lowest priority) - config/inertia-toast.php

Example: Backend sets 5s, per-toast overrides to 3s

// Backend config: duration = 5000
Toast::success('Quick message', duration: 3000); // Uses 3000ms
Toast::success('Normal message'); // Uses 5000ms from config

Duration recommendations

Choose appropriate durations based on the toast type and message length:

• Success messages - 3000-5000ms (3-5 seconds)
• Error messages - 7000-10000ms (7-10 seconds) - Users need time to read error details
• Info messages - 5000ms (5 seconds)
• Warning messages - 7000-10000ms (7-10 seconds) - Important warnings need attention
• Long messages - Add 1000ms for every 10-15 additional words

Users can manually dismiss toasts at any time by clicking the close button, so don’t worry too much about the exact duration - err on the side of giving users more time to read.