v0.1.0

Appearance

Toast <l-toast> ​

Toasts are used to display brief, non-blocking notifications that auto-dismiss. Commonly used to confirm actions, report errors, or surface system messages without interrupting the user's workflow.

HTML tag<l-toast>
⏣Native HTML
⬡Progressive
◇Custom
⬢Shadow DOM
Custom Element (no Shadow DOM)

Options ​

Basic ​

Place a single <l-toast> element anywhere inside the <body>. Call toast() to display notifications.

Code
html
<button
  class="l-button"
  onclick="toast({ text: 'This is a toast notification!' })"
>
  Show notification
</button>

Variants ​

Pass variant in the options to apply accent colors: info, success, warning, danger.

Code
html
<div class="flex gap-2 flex-wrap">
  <button
    class="l-button"
    onclick="toast({ text: 'Neutral message' })"
  >
    Neutral
  </button>
  <button
    class="l-button"
    onclick="toast({ text: 'Informational message', variant: 'info' })"
  >
    Info
  </button>
  <button
    class="l-button"
    onclick="toast({ text: 'Operation successful!', variant: 'success' })"
  >
    Success
  </button>
  <button
    class="l-button"
    onclick="toast({ text: 'Please be careful', variant: 'warning' })"
  >
    Warning
  </button>
  <button
    class="l-button"
    onclick="toast({ text: 'Something went wrong', variant: 'danger' })"
  >
    Danger
  </button>
</div>

Heading ​

Pass heading in the options to display a title above the message.

Code
html
<div class="flex gap-2 flex-wrap">
  <button
    class="l-button"
    onclick="
      toast({
        text: 'Your changes have been saved.',
        heading: 'Saved',
        variant: 'success',
        timer: true,
      })
    "
  >
    Success
  </button>
  <button
    class="l-button"
    onclick="
      toast({
        text: 'This action cannot be undone.',
        heading: 'Warning',
        variant: 'warning',
        timer: true,
      })
    "
  >
    Warning
  </button>
  <button
    class="l-button"
    onclick="
      toast({ text: 'Please try again later.', heading: 'Error', variant: 'danger', timer: true })
    "
  >
    Error
  </button>
</div>

Icon ​

Pass icon with an Iconify icon name to replace the accent bar with an icon, colored by variant.

Code
html
<div class="flex gap-2 flex-wrap">
  <button
    class="l-button"
    onclick="
      toast({
        text: 'Informational message',
        heading: 'Info',
        variant: 'info',
        icon: 'lucide:info',
      })
    "
  >
    Info
  </button>
  <button
    class="l-button"
    onclick="
      toast({
        text: 'Operation successful!',
        heading: 'Success',
        variant: 'success',
        icon: 'lucide:circle-check',
      })
    "
  >
    Success
  </button>
  <button
    class="l-button"
    onclick="
      toast({
        text: 'Please be careful',
        heading: 'Warning',
        variant: 'warning',
        icon: 'lucide:triangle-alert',
      })
    "
  >
    Warning
  </button>
  <button
    class="l-button"
    onclick="
      toast({
        text: 'Something went wrong',
        heading: 'Error',
        variant: 'danger',
        icon: 'lucide:circle-x',
      })
    "
  >
    Danger
  </button>
</div>

Duration ​

Control how long the toast stays visible. Set to 0 for persistent notifications that must be manually dismissed.

Code
html
<div class="flex gap-2 flex-wrap">
  <button
    class="l-button"
    onclick="toast({ text: 'Closes in 3 seconds', duration: 3000 })"
  >
    3s
  </button>
  <button
    class="l-button"
    onclick="toast({ text: 'Closes in 10 seconds', duration: 10000 })"
  >
    10s
  </button>
  <button
    class="l-button"
    onclick="toast({ text: 'Stays until dismissed', duration: 0 })"
  >
    Persistent
  </button>
  <button
    class="l-button"
    onclick="toast({ text: 'With countdown bar', duration: 5000, timer: true })"
  >
    With timer
  </button>
</div>

Placement ​

Position the toast stack using the placement attribute.

Code
html
<div class="flex gap-2 flex-wrap">
  <button
    class="l-button"
    onclick="
      document.querySelector('l-toast').placement = 'top-start';
      toast({ text: 'Top start' });
    "
  >
    Top start
  </button>
  <button
    class="l-button"
    onclick="
      document.querySelector('l-toast').placement = 'top-center';
      toast({ text: 'Top center' });
    "
  >
    Top center
  </button>
  <button
    class="l-button"
    onclick="
      document.querySelector('l-toast').placement = 'top-end';
      toast({ text: 'Top end' });
    "
  >
    Top end
  </button>
  <button
    class="l-button"
    onclick="
      document.querySelector('l-toast').placement = 'bottom-start';
      toast({ text: 'Bottom start' });
    "
  >
    Bottom start
  </button>
  <button
    class="l-button"
    onclick="
      document.querySelector('l-toast').placement = 'bottom-center';
      toast({ text: 'Bottom center' });
    "
  >
    Bottom center
  </button>
  <button
    class="l-button"
    onclick="
      document.querySelector('l-toast').placement = 'bottom-end';
      toast({ text: 'Bottom end' });
    "
  >
    Bottom end
  </button>
</div>

Programmatic API ​

js
import { toast } from 'luxen-ui/toast';

// Basic
toast({ text: 'Saved successfully!' });

// With variant
toast({ text: 'File uploaded', variant: 'success' });

// With heading and custom duration
toast({
  text: 'Undo this action?',
  heading: 'Warning',
  variant: 'warning',
  duration: 0,
});

Features ​

  • Function-based API — call toast({ text: '...' }) from anywhere, no component wiring needed
  • Timer pausing on hover & focus — countdown pauses when hovered or focused, resumes when the pointer or focus leaves
  • Timer pausing on hidden tab — countdown pauses when the browser tab loses visibility, resumes with the remaining time when the user returns
  • Swipe to dismiss — drag a toast horizontally to dismiss it; works with mouse, touch, and pen input
  • @starting-style enter animations — smooth CSS entry transitions using the @starting-style at-rule
  • Keyboard dismiss — press Escape to dismiss the most recent toast
  • FLIP reorder animations — remaining toasts animate smoothly into their new positions when one is dismissed

Accessibility ​

Criteria ​

Live region

Container uses role="log" with aria-live="polite" for screen reader announcements

WCAG4.1.3
RGAA7.5
Role

Items use role="status" (role="alert" for danger variant)

WCAG4.1.2
Accessible name

Heading and message linked via aria-labelledby / aria-describedby

WCAG4.1.2
RGAA11.1
Decorative elements

Icons, accent bar, and timer bar are hidden with aria-hidden="true"

WCAG1.1.1
RGAA1.1
Timer pausing

Timer pauses on hover and focus, providing keyboard parity

WCAG2.2.1
Motion

Respects prefers-reduced-motion

WCAG2.3.3

Keyboard interactions ​

Escape
Dismisses the most recent toast
Tab
Moves focus into the toast (pauses the auto-dismiss timer)

API reference ​

Importing ​

js
// Side-effect import (registers <l-toast> element)
import 'luxen-ui/toast';

// Or import the standalone function (auto-creates <l-toast>)
import { toast } from 'luxen-ui/toast';
toast({ text: 'Hello!' });
css
@import 'luxen-ui/css/toast';
@import 'luxen-ui/css/close-button';

Attributes & Properties ​

placementAttribute
Position of the toast stack: top-start, top-center, top-end (default), bottom-start, bottom-center, bottom-end
durationAttribute
Default auto-dismiss delay in ms. Default 5000. Set to 0 or Infinity to keep open until dismissed
variantAttribute
Default variant for toast items: info, success, warning, danger

Methods ​

toast()Method
Creates and shows a toast notification

ToastOptions ​

textProperty
The message text to display. Required unless html is provided
htmlProperty
HTML content for the message, sanitized via the Sanitizer API. Ignored if text is provided
headingProperty
Heading text displayed above the message
iconProperty
Iconify icon name (e.g. lucide:check). Replaces the accent bar, colored by variant
variantProperty
Override variant for this toast
durationProperty
Override auto-dismiss delay in ms. 0 or Infinity to keep open until dismissed
timerProperty
Show a countdown progress bar at the bottom

Events ​

l-showEvent
Emitted when a toast begins to show. Cancelable
l-after-showEvent
Emitted after the show animation completes
l-hideEvent
Emitted when a toast begins to hide. Cancelable
l-after-hideEvent
Emitted after the hide animation completes and toast is removed

CSS classes ​

l-toast-itemClass
Toast item custom element (generated internally)
.l-toast-accentClass
Left accent bar, colored by variant
.l-toast-contentClass
Content area
.l-toast-headingClass
Heading text
.l-toast-messageClass
Message text
.l-toast-timerClass
Countdown progress bar (auto-added for timed toasts)

CSS custom properties ​

--gapProperty
Gap between stacked items. Default 0.5rem
--widthProperty
Width of the toast stack. Default 28rem
--show-durationProperty
Show animation duration. Default 200ms
--hide-durationProperty
Hide animation duration. Default 200ms