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

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

<Tabs>
  <Tab title="PHP (Backend)">
    Configure the default duration in the config file:

    ```php config/inertia-toast.php theme={null}
    return [
        'duration' => 5000, // 5 seconds (in milliseconds)
        'position' => 'top-right',
        'max_visible' => 5,
        'prop_key' => 'toasts',
    ];
    ```
  </Tab>

  <Tab title="Vue 3 (Frontend)">
    Set the duration when registering the plugin:

    ```js resources/js/app.js theme={null}
    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')
    ```
  </Tab>

  <Tab title="React (Frontend)">
    Set the duration in the `ToastProvider` config:

    ```jsx resources/js/app.tsx theme={null}
    import { ToastProvider, Toasts } from '@laravel-inertia-toast/react'

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

### Per-toast duration

Override the default duration for individual toasts.

<Tabs>
  <Tab title="PHP Facade">
    ```php theme={null}
    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
    );
    ```
  </Tab>

  <Tab title="PHP Helper">
    ```php theme={null}
    // 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();
    ```
  </Tab>

  <Tab title="Vue 3">
    ```typescript theme={null}
    <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>
    ```
  </Tab>

  <Tab title="React">
    ```jsx theme={null}
    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>
        </>
      )
    }
    ```
  </Tab>
</Tabs>

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

## Max visible toasts

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

<Tabs>
  <Tab title="PHP (Backend)">
    ```php config/inertia-toast.php theme={null}
    return [
        'duration' => 5000,
        'position' => 'top-right',
        'max_visible' => 5, // Maximum 5 toasts at once
        'prop_key' => 'toasts',
    ];
    ```
  </Tab>

  <Tab title="Vue 3 (Frontend)">
    ```js resources/js/app.js theme={null}
    app.use(InertiaToast, {
        duration: 5000,
        position: 'top-right',
        maxVisible: 5, // Maximum 5 toasts at once
    })
    ```
  </Tab>

  <Tab title="React (Frontend)">
    ```jsx resources/js/app.tsx theme={null}
    <ToastProvider
        config={{
            duration: 5000,
            position: 'top-right',
            maxVisible: 5, // Maximum 5 toasts at once
        }}
    >
        <App {...props} />
        <Toasts />
    </ToastProvider>
    ```
  </Tab>
</Tabs>

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

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

## Inertia flash key

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

```php config/inertia-toast.php theme={null}
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

<Warning>
  If you change the `prop_key`, make sure it doesn't conflict with other Inertia shared props in your application.
</Warning>

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

<CodeGroup>
  ```php Example: Backend sets 5s, per-toast overrides to 3s theme={null}
  // Backend config: duration = 5000
  Toast::success('Quick message', duration: 3000); // Uses 3000ms
  Toast::success('Normal message'); // Uses 5000ms from config
  ```

  ```js Example: Frontend overrides backend default theme={null}
  // Backend config has duration: 5000
  // Frontend overrides it:
  app.use(InertiaToast, {
      duration: 8000, // All toasts will use 8000ms by default
  })
  ```
</CodeGroup>

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

<Note>
  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.
</Note>