> ## Documentation Index
> Fetch the complete documentation index at: https://veekthoven-laravel-inertia-toast-24-61.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
php artisan vendor:publish --tag=inertia-toast-config
```

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

### Configuration options

```php theme={null}
<?php

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

### duration

<Info>
  **Type:** `int`\
  **Default:** `5000`
</Info>

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

```php theme={null}
// config/inertia-toast.php
'duration' => 8000, // 8 seconds
```

You can override this for individual toasts:

```php theme={null}
Toast::success('Quick message', duration: 3000);
toast('Longer message')->duration(10000)->info();
```

### position

<Info>
  **Type:** `string`\
  **Default:** `'top-right'`
</Info>

Where toasts appear on screen. Available options:

* `top-right`
* `top-left`
* `top-center`
* `bottom-right`
* `bottom-left`
* `bottom-center`

```php theme={null}
// config/inertia-toast.php
'position' => 'bottom-right',
```

<Note>
  The position can also be configured on the frontend when registering the plugin or provider.
</Note>

### max\_visible

<Info>
  **Type:** `int`\
  **Default:** `5`
</Info>

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

```php theme={null}
// config/inertia-toast.php
'max_visible' => 3, // Only show 3 toasts at a time
```

### prop\_key

<Info>
  **Type:** `string`\
  **Default:** `'toasts'`
</Info>

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

```php theme={null}
// config/inertia-toast.php
'prop_key' => 'notifications',
```

<Warning>
  If you change the `prop_key`, you must also update your frontend configuration to match. Otherwise, toasts won't be displayed.
</Warning>

## Frontend configuration

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

### Vue 3

Pass options when installing the plugin:

```js theme={null}
// 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:

```typescript theme={null}
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:

```tsx theme={null}
// 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:

```typescript theme={null}
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

```php theme={null}
// 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:

<Tabs>
  <Tab title="Top positions">
    ```js theme={null}
    // Top right corner (default)
    position: 'top-right'

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

    // Top center
    position: 'top-center'
    ```
  </Tab>

  <Tab title="Bottom positions">
    ```js theme={null}
    // Bottom right corner
    position: 'bottom-right'

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

    // Bottom center
    position: 'bottom-center'
    ```
  </Tab>
</Tabs>

## 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

```php theme={null}
// 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
);
```

<Tip>
  For important messages that users should read carefully, consider using a longer duration.
</Tip>

## 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

```js theme={null}
// For a clean, minimal interface
app.use(InertiaToast, {
  maxVisible: 2
})

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

<Warning>
  Setting `maxVisible` too high can overwhelm users. Consider queuing operations or consolidating related toasts into a single message.
</Warning>

## Custom prop key

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

### Backend

```php theme={null}
// config/inertia-toast.php
'prop_key' => 'flash_messages',
```

### Vue

```js theme={null}
app.use(InertiaToast, {
  propKey: 'flash_messages'
})
```

### React

```tsx theme={null}
<ToastProvider
  config={{
    propKey: 'flash_messages'
  }}
>
  {/* ... */}
</ToastProvider>
```

<Warning>
  The `propKey` value must match between backend and frontend, otherwise toasts won't be displayed.
</Warning>

## Environment-specific configuration

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

```php theme={null}
// 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:

```bash theme={null}
# .env
TOAST_DURATION=8000
TOAST_POSITION=bottom-right
TOAST_MAX_VISIBLE=3
```

## Complete examples

<CodeGroup>
  ```php Backend config theme={null}
  <?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',
  ];
  ```

  ```js Vue config theme={null}
  // resources/js/app.js
  import { createApp } from 'vue'
  import { InertiaToast } from '@laravel-inertia-toast/vue'

  const app = createApp(App)

  app.use(InertiaToast, {
    duration: 6000,
    position: 'bottom-right',
    maxVisible: 3,
    propKey: 'notifications'
  })

  app.mount('#app')
  ```

  ```tsx React config theme={null}
  // 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: 6000,
          position: 'bottom-right',
          maxVisible: 3,
          propKey: 'notifications'
        }}
      >
        <App {...props} />
        <Toasts />
      </ToastProvider>
    )
  }
  ```
</CodeGroup>