Toast

Introduction

The Toast component provides non-intrusive notifications that appear temporarily to inform users about the result of an action or system event. It includes a provider component that manages the toast stack and a JavaScript API for triggering toasts programmatically.

When to use

Toast notifications are ideal for:

Success confirmations (“Changes saved”)
Error messages (“Could not connect”)
Informational updates (“New message received”)
Warnings (“Session expiring soon”)
Background process status (“Sync in progress”)

Quick example

Usage

Learn how to implement the Toast component in your project, from basic setup to advanced configurations.

Basic setup

Add the ToastProvider once in your layout (typically near the end of the body):

---
import { ToastProvider } from 'accessible-astro-components'
---

<html>
  <body>
    <slot />
    <ToastProvider />
  </body>
</html>

Then trigger toasts anywhere using the global API:

<button id="save-button">Save</button>

<script>
  document.getElementById('save-button')?.addEventListener('click', () => {
    window.toast?.success('Saved successfully.')
  })
</script>

Toast variants

Use the typed helper methods for common toast types:

// Success (green)
window.toast?.success('Changes saved.')

// Error (red)
window.toast?.error('Something went wrong.')

// Info (blue)
window.toast?.info('New updates available.')

// Warning (yellow)
window.toast?.warning('Your session will expire soon.')

// Default (neutral)
window.toast?.show({ message: 'Notification' })

Persistent toasts

Set duration: 0 to create a toast that doesn’t auto-dismiss:

window.toast?.show({
  message: 'Background sync in progress...',
  type: 'info',
  duration: 0,
})

Custom duration

Override the default duration (in milliseconds) per toast:

window.toast?.success('Quick message', 2000)  // 2 seconds
window.toast?.error('Important error', 10000) // 10 seconds

Dismissing toasts

// Dismiss a specific toast by ID
const id = window.toast?.success('Hello')
window.toast?.dismiss(id)

// Dismiss all toasts
window.toast?.dismissAll()

Positioning

Control where toasts appear using the position prop:

<ToastProvider position="top-center" />

Available positions: bottom-right (default), bottom-left, bottom-center, top-right, top-left, top-center.

Stacking contexts

Render ToastProvider near the end of your layout body when possible. If the provider must be nested inside an element that creates a stacking context, set portal to move the provider to document.body after initialization:

<ToastProvider portal />

Props

ToastProvider

Configure the toast container using these props:

Prop	Type	Default	Description
`position`	`string`	`'bottom-right'`	Position in viewport. Options: `bottom-right`, `bottom-left`, `bottom-center`, `top-right`, `top-left`, `top-center`
`duration`	`number`	`5000`	Default auto-dismiss time in milliseconds. Set to `0` for persistent toasts
`maxToasts`	`number`	`5`	Maximum visible toasts. Oldest are dismissed when exceeded
`ariaLabel`	`string`	`'Notifications'`	Accessible label for the toast region
`zIndex`	`string \| number`	`'var(--z-index-8, 80)'`	CSS z-index value applied through `--toast-z-index`
`portal`	`boolean`	`false`	Moves the provider to `document.body` on initialization to escape ancestor stacking contexts
`class`	`string`	`''`	Additional CSS classes

Toast

Individual toast props (used internally, but useful for understanding the API):

Prop	Type	Default	Description
`message`	`string`	`'Notification'`	Toast message content
`type`	`string`	`'default'`	Visual variant: `default`, `info`, `success`, `warning`, `error`
`dismissible`	`boolean`	`true`	Whether to show the dismiss button
`dismissLabel`	`string`	`'Dismiss notification'`	Accessible label for dismiss button (for i18n)
`class`	`string`	`''`	Additional CSS classes

JavaScript API

The window.toast object provides these methods:

Method	Signature	Description
`show`	`(options: ToastOptions) => string`	Show a toast with full options, returns toast ID
`success`	`(message: string, duration?: number) => string`	Show success toast
`error`	`(message: string, duration?: number) => string`	Show error toast
`info`	`(message: string, duration?: number) => string`	Show info toast
`warning`	`(message: string, duration?: number) => string`	Show warning toast
`dismiss`	`(id: string, immediate?: boolean) => void`	Dismiss specific toast
`dismissAll`	`() => void`	Dismiss all toasts

ToastOptions

type ToastOptions = {
  message: string
  type?: 'info' | 'success' | 'warning' | 'error' | 'default'
  duration?: number
  dismissible?: boolean
}

Events

The toast system dispatches custom events on document:

// Fired when a toast is shown
document.addEventListener('toast:show', (e) => {
  console.log('Toast shown:', e.detail.id, e.detail.type, e.detail.message)
})

// Fired when a toast is dismissed
document.addEventListener('toast:dismiss', (e) => {
  console.log('Toast dismissed:', e.detail.id)
})

Accessibility

Accessibility is built into the core of this component:

Live region: Uses role="log" for polite screen reader announcements
Keyboard support: Press Escape to dismiss all toasts
Non-intrusive: Toasts don’t steal focus from the user’s current task
Screen reader friendly: Type is announced before the message (e.g., “success: Changes saved”)
Reduced motion: Animations respect prefers-reduced-motion
Dismiss button: Each toast has an accessible dismiss button

Styling

Customize the Toast component while maintaining its accessibility features.

Custom CSS
Tailwind Classes

<style is:global>
  .toast-provider {
    /* Adjust positioning */
    --space-l: 2rem;
  }

  .toast {
    /* Custom appearance */
    border-radius: 0.75rem;
    box-shadow: 0 10px 15px -3px hsl(0 0% 0% / 0.1);
  }

  .toast.type-success {
    --color-success-bg: hsl(142 76% 95%);
    --color-success-border: hsl(142 76% 36%);
    --color-success-text: hsl(142 76% 20%);
  }

  .toast.type-error {
    --color-error-bg: hsl(0 84% 95%);
    --color-error-border: hsl(0 84% 60%);
    --color-error-text: hsl(0 84% 20%);
  }

  .toast-dismiss:focus-visible {
    outline-color: currentColor;
    outline-offset: 2px;
  }
</style>

<ToastProvider
  class="[&_.toast]:rounded-xl [&_.toast]:shadow-lg"
/>

CSS custom properties

The toast system uses these CSS custom properties for theming:

/* Spacing and sizing */
--space-xs
--space-2xs
--space-l
--radius-m

/* Type-specific colors (for each type: default, info, success, warning, error) */
--color-{type}-bg
--color-{type}-border
--color-{type}-text

/* Animation */
--toast-translate
--animation-timing

/* Elevation */
--elevation-2
--toast-z-index

Toast

Introduction

When to use

Quick example

Usage

Basic setup

Toast variants

Persistent toasts

Custom duration

Dismissing toasts

Positioning

Stacking contexts

Props

ToastProvider

Toast

JavaScript API

ToastOptions

Events

Accessibility

Styling

CSS custom properties

Interactive examples

All variants

Persistent toast