Toast

A notification toast component with auto-dismiss and Alpine.js integration.

Alpine.js Required

This component requires Alpine.js to be loaded in your layout for toast notifications. See the installation guide for setup instructions.

Live Preview

View in the Styleguide →

Basic Usage

<x-basekit-ui::toast variant="success" title="Saved!" message="Your changes have been saved." />

Props

Prop	Type	Default	Description
variant	string	'info'	Toast style variant
duration	int	3000	Auto-dismiss duration in ms (0 to disable)
is-dismissible	bool	true	Show the manual dismiss (×) button
title	string	null	Toast title text
message	string	null	Toast body text (alternative to default slot)
icon	string	null	Heroicon name (defaults to variant icon)
color	string	null	Quick color shortcut. Sets background, text, and border simultaneously.
background	string	null	Custom background color.
text	string	null	Custom text color.
border	string	null	Custom border color.

Slots

Slot	Description
default	Toast body content (overrides message prop)
icon	Custom icon SVG (overrides icon prop and default)
title	Custom title content (overrides title prop)
actions	Action buttons rendered below the message

Variants

Supported variants: primary, secondary, success, warning, danger, info, ghost.

<x-basekit-ui::toast variant="primary" title="Primary update" message="A key announcement for all users." :duration="0" />
<x-basekit-ui::toast variant="secondary" title="Secondary notice" message="Background sync completed successfully." :duration="0" />
<x-basekit-ui::toast variant="info" title="Update available" message="Version 2.0 is ready." :duration="0" />
<x-basekit-ui::toast variant="success" title="Changes saved" message="Your settings have been updated." :duration="0" />
<x-basekit-ui::toast variant="warning" title="Storage almost full" message="You're using 95% of your storage." :duration="0" />
<x-basekit-ui::toast variant="danger" title="Connection failed" message="Unable to reach the server." :duration="0" />
<x-basekit-ui::toast variant="ghost" title="Ghost note" message="This is a lightweight, low-emphasis toast." :duration="0" />

With Icons

With Heroicon

Pass any Heroicon name via the icon prop:

<x-basekit-ui::toast variant="info" icon="bell" title="New message" message="You have 3 notifications." />

Using Icon Slot

<x-basekit-ui::toast variant="success" title="Milestone reached" message="You've completed 100 tasks!">
    <x-slot:icon>
        <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
            <path stroke-linecap="round" stroke-linejoin="round"
                d="M9 12.75L11.25 15 15 9.75M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
        </svg>
    </x-slot:icon>
</x-basekit-ui::toast>

With Actions

<x-basekit-ui::toast variant="warning" title="Connection lost" message="Reconnecting to server..." :duration="0">
    <x-slot:actions>
        <x-basekit-ui::button size="sm" variant="ghost">Retry</x-basekit-ui::button>
    </x-slot:actions>
</x-basekit-ui::toast>

Duration

{{-- Auto-dismiss after 5 seconds --}}
<x-basekit-ui::toast variant="success" message="Saved!" :duration="5000" />

{{-- Never auto-dismiss --}}
<x-basekit-ui::toast variant="info" message="Please read this carefully." :duration="0" />

Toast Container

For positioning multiple toasts (e.g. flash messages):

<div class="fixed top-4 right-4 z-50 space-y-2">
    @if(session('success'))
        <x-basekit-ui::toast variant="success" :message="session('success')" />
    @endif

    @if(session('error'))
        <x-basekit-ui::toast variant="danger" :message="session('error')" />
    @endif
</div>

Custom Classes

Override or extend styles with the class attribute. The class attribute is automatically merged with the component's internal classes using Laravel's built-in class() method:

<x-basekit-ui::toast
    variant="success"
    message="Profile updated"
    class="mt-2"
/>

Custom Colors

Override the component's default variant colors using the color shortcut prop or granular background, text, and border props.

The color prop accepts Tailwind v4 color names (e.g., indigo-500, pink-200, emerald-700) or any raw CSS color value (hex, rgb, hsl, named colors).

Note: When using Tailwind color names, the component automatically selects a contrasting text color (white on shades ≥500, dark on shades ≤400) and computes a lighter border shade.

With Tailwind Colors

<x-basekit-ui::toast color="indigo-500" title="Update available" message="Version 2.0 is ready." />

With Raw CSS Colors

<x-basekit-ui::toast background="#EEF2FF" text="#4338CA" border="#C7D2FE" title="Update available" message="Version 2.0 is ready." />

Granular Control

<x-basekit-ui::toast
    background="indigo-500"
    text="white"
    border="indigo-300"
    title="Update available"
    message="Version 2.0 is ready."
/>

CSS Variables

Customize toast appearance via CSS variables:

:root {
  /* Toast - Base */
  --toast-radius: var(--radius-md);
  --toast-shadow:
    0 4px 12px -2px rgba(0, 0, 0, 0.08), 0 2px 4px -1px rgba(0, 0, 0, 0.04);

  /* Toast - Variants */
  --toast-bg-primary: var(--color-primary-50);
  --toast-text-primary: var(--color-primary-900);
  --toast-border-primary: var(--color-primary-500);

  --toast-bg-info: var(--color-info-50);
  --toast-text-info: var(--color-info-900);
  --toast-border-info: var(--color-info-500);

  --toast-bg-secondary: var(--color-slate-50);
  --toast-text-secondary: var(--color-slate-900);
  --toast-border-secondary: var(--color-slate-400);

  --toast-bg-success: var(--color-success-50);
  --toast-text-success: var(--color-success-900);
  --toast-border-success: var(--color-success-500);

  --toast-bg-warning: var(--color-warning-50);
  --toast-text-warning: var(--color-warning-900);
  --toast-border-warning: var(--color-warning-500);

  --toast-bg-danger: var(--color-danger-50);
  --toast-text-danger: var(--color-danger-900);
  --toast-border-danger: var(--color-danger-500);

  --toast-bg-ghost: transparent;
  --toast-text-ghost: var(--color-slate-700);
  --toast-border-ghost: transparent;
}

Dark Mode

Dark mode overrides are applied automatically when a parent element has the .dark class:

.dark {
  --toast-shadow:
    0 4px 12px -2px rgba(0, 0, 0, 0.3), 0 2px 4px -1px rgba(0, 0, 0, 0.2);

  --toast-bg-primary: var(--color-primary-950);
  --toast-text-primary: var(--color-primary-200);
  --toast-border-primary: var(--color-primary-500);

  --toast-bg-info: var(--color-info-950);
  --toast-text-info: var(--color-info-200);
  --toast-border-info: var(--color-info-500);

  --toast-bg-secondary: var(--color-slate-800);
  --toast-text-secondary: var(--color-slate-200);
  --toast-border-secondary: var(--color-slate-400);

  --toast-bg-success: var(--color-success-950);
  --toast-text-success: var(--color-success-200);
  --toast-border-success: var(--color-success-500);

  --toast-bg-warning: var(--color-warning-950);
  --toast-text-warning: var(--color-warning-200);
  --toast-border-warning: var(--color-warning-500);

  --toast-bg-danger: var(--color-danger-950);
  --toast-text-danger: var(--color-danger-200);
  --toast-border-danger: var(--color-danger-500);

  --toast-text-ghost: var(--color-slate-400);

  /* Dismiss */
  --toast-dismiss-hover-bg: rgba(255, 255, 255, 0.1);
}

For dark mode token details, see Theming — Dark Mode.

Configuration

Configure defaults in config/basekit-laravel-ui.php:

'toast' => [
    'enabled' => true,
    'variants' => ['primary', 'secondary', 'success', 'warning', 'danger', 'info', 'ghost'],
    'default_variant' => 'info',
],