Configuration

Configure toast behavior and appearance for both backend and frontend

Laravel Inertia Toast can be configured on both the backend (PHP) and frontend (Vue/React) to customize the default behavior of your toast notifications.

Backend configuration

Publish the configuration file to customize backend defaults:

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

This creates a config/inertia-toast.php file in your Laravel application.

Configuration options

<?php

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

duration

Type: int
Default: 5000

The default duration in milliseconds before a toast auto-dismisses. This value is sent to the frontend and can be overridden per-toast.

// config/inertia-toast.php
'duration' => 8000, // 8 seconds

You can override this for individual toasts:

Toast::success('Quick message', duration: 3000);
toast('Longer message')->duration(10000)->info();

position

Type: string
Default: 'top-right'

Where toasts appear on screen. Available options:

• top-right
• top-left
• top-center
• bottom-right
• bottom-left
• bottom-center

// config/inertia-toast.php
'position' => 'bottom-right',

The position can also be configured on the frontend when registering the plugin or provider.

max_visible

Type: int
Default: 5

The maximum number of toasts visible at once. When this limit is exceeded, the oldest toasts are automatically removed first.

// config/inertia-toast.php
'max_visible' => 3, // Only show 3 toasts at a time

prop_key

Type: string
Default: 'toasts'

The key used when flashing toast data via Inertia::flash(). This is the property name that will be available in your Inertia page props.

// config/inertia-toast.php
'prop_key' => 'notifications',

If you change the prop_key, you must also update your frontend configuration to match. Otherwise, toasts won’t be displayed.

Frontend configuration

You can configure frontend toast behavior when registering the Vue plugin or React provider.

Vue 3

Pass options when installing 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,
  position: 'top-right',
  maxVisible: 5,
  propKey: 'toasts'
})

app.mount('#app')

Options

All options are optional and will use defaults if not provided:

interface InertiaToastOptions {
  duration?: number      // Default: 5000
  position?: string      // Default: 'top-right'
  maxVisible?: number    // Default: 5
  propKey?: string       // Default: 'toasts'
}

React

Pass configuration to the <ToastProvider> component:

// resources/js/app.tsx
import { createRoot } from 'react-dom/client'
import { ToastProvider, Toasts } from '@laravel-inertia-toast/react'

setup({ el, App, props }) {
  const root = createRoot(el)

  root.render(
    <ToastProvider
      config={{
        duration: 5000,
        position: 'top-right',
        maxVisible: 5,
        propKey: 'toasts'
      }}
    >
      <App {...props} />
      <Toasts />
    </ToastProvider>
  )
}

Config prop

The config prop accepts a partial configuration object:

interface ToastConfig {
  duration?: number      // Default: 5000
  position?: string      // Default: 'top-right'
  maxVisible?: number    // Default: 5
  propKey?: string       // Default: 'toasts'
}

Configuration precedence

Configuration values follow this precedence order (highest to lowest):

1. Per-toast options - Options passed when creating a specific toast
2. Frontend configuration - Options passed to plugin/provider
3. Backend configuration - Values in config/inertia-toast.php
4. Package defaults - Built-in default values

Example

// Backend config: duration = 5000
// Frontend config: duration = 8000

// This toast will show for 8 seconds (frontend config)
Toast::success('Default duration');

// This toast will show for 3 seconds (per-toast override)
Toast::success('Custom duration', duration: 3000);

Position examples

Here’s how different position values affect toast placement:

Top positions

// Top right corner (default)
position: 'top-right'

// Top left corner
position: 'top-left'

// Top center
position: 'top-center'

Bottom positions

// Bottom right corner
position: 'bottom-right'

// Bottom left corner
position: 'bottom-left'

// Bottom center
position: 'bottom-center'

Duration guidelines

Recommended duration values based on message length:

• Short messages (1-20 chars): 3000-4000ms
• Medium messages (21-50 chars): 5000-6000ms (default)
• Long messages (51+ chars): 8000-10000ms
• Critical warnings: 10000-15000ms

// Short success message
Toast::success('Saved!', duration: 3000);

// Medium info message
Toast::info('Your profile has been updated successfully.');

// Long warning message
Toast::warning(
    'Your subscription will expire in 3 days. Please update your payment method to continue using our service.',
    duration: 10000
);

For important messages that users should read carefully, consider using a longer duration.

Max visible recommendations

The optimal number of simultaneous toasts depends on your use case:

• Most applications: 3-5 toasts (default: 5)
• Bulk operations: 8-10 toasts
• Minimal UI: 1-2 toasts

// For a clean, minimal interface
app.use(InertiaToast, {
  maxVisible: 2
})

// For bulk operations with many notifications
app.use(InertiaToast, {
  maxVisible: 10
})

Setting maxVisible too high can overwhelm users. Consider queuing operations or consolidating related toasts into a single message.

Custom prop key

If you need to use a different Inertia flash key (for example, to avoid conflicts with existing code):

Backend

// config/inertia-toast.php
'prop_key' => 'flash_messages',

Vue

app.use(InertiaToast, {
  propKey: 'flash_messages'
})

React

<ToastProvider
  config={{
    propKey: 'flash_messages'
  }}
>
  {/* ... */}
</ToastProvider>

The propKey value must match between backend and frontend, otherwise toasts won’t be displayed.

Environment-specific configuration

You can use environment variables to adjust toast behavior across different environments:

// config/inertia-toast.php
return [
    'duration' => env('TOAST_DURATION', 5000),
    'position' => env('TOAST_POSITION', 'top-right'),
    'max_visible' => env('TOAST_MAX_VISIBLE', 5),
];

Then in your .env file:

# .env
TOAST_DURATION=8000
TOAST_POSITION=bottom-right
TOAST_MAX_VISIBLE=3

Complete examples

Backend config

<?php

// config/inertia-toast.php
return [
    // Show toasts for 6 seconds
    'duration' => 6000,

    // Position in bottom right
    'position' => 'bottom-right',

    // Show max 3 toasts at once
    'max_visible' => 3,

    // Use custom flash key
    'prop_key' => 'notifications',
];