Library · Foundations

Toast

Stacked, auto-dismissing notification toasts driven by a global window.toast API (show/success/error/info/warning/dismiss/dismissAll) exposed by ToastProvider; Toast is the individual message rendered inside it.

Figma: Primitives / Toast ↗
Live preview — edit theme bottom-right 
---
import Toast from "../components/primitives/toast/Toast.astro";
import ToastProvider from "../components/primitives/toast/ToastProvider.astro";
import Button from "../components/primitives/button/Button.astro";
---
<!-- Live toasts render fixed to the viewport corner (bottom-right), outside this preview box -->
<Button variant="outlined" type="info" data-toast-trigger="info">Info toast</Button>
<Button variant="outlined" type="success" data-toast-trigger="success">Success toast</Button>
<Button variant="outlined" type="warning" data-toast-trigger="warning">Warning toast</Button>
<Button variant="outlined" type="error" data-toast-trigger="error">Error toast</Button>

<Toast data-state="ready" message="Static toast anatomy" type="info" dismissible={false} />

<ToastProvider position="bottom-right" />

<script>
  function wireToastTriggers() {
    document.querySelectorAll<HTMLButtonElement>('[data-toast-trigger]').forEach((button) => {
      button.addEventListener('click', () => {
        const type = button.dataset.toastTrigger
        switch (type) {
          case 'info':
            window.toast.info('This is an info toast.')
            break
          case 'success':
            window.toast.success('This is a success toast.')
            break
          case 'warning':
            window.toast.warning('This is a warning toast.')
            break
          case 'error':
            window.toast.error('This is an error toast.')
            break
        }
      })
    })
  }

  wireToastTriggers()
  document.addEventListener('astro:after-swap', wireToastTriggers)
</script>

Props

NameTypeRequiredDescription
class string — Additional classes to apply to the toast
id string — Optional id for the toast
message string — Toast message content
type 'info' | 'success' | 'warning' | 'error' | 'default' — Type of toast (default: "default")
dismissible boolean — Whether the toast is dismissible (default: true)
dismissLabel string — Accessible label for the dismiss button (default: "Dismiss notification")
[key: string] string | number | boolean | undefined — HTML attributes to spread on the toast
Provider: class string — Additional classes to apply to the toast provider
Provider: position | 'bottom-right' | 'bottom-left' | 'bottom-center' | 'top-right' | 'top-left' | 'top-center' — Toast position in the viewport (default: "bottom-right")
Provider: duration number — Default duration before auto-dismiss (ms)
Provider: maxToasts number — Maximum number of toasts to display (default: 5)
Provider: ariaLabel string — Accessible label for the toast region (default: "Notifications")
Provider: zIndex string | number — CSS z-index value for the toast provider (default: "var(--z-index-8, 80)")
Provider: portal boolean — Move the provider to document.body on initialization to escape ancestor stacking contexts (default: false)
Provider: style string — Inline styles to apply to the toast provider. These are appended after the computed zIndex style, so avoid declaring `--toast-z-index` here unless you intentionally want to override `zIndex`.
Provider: [key: string] string | number | boolean | undefined — HTML attributes to spread on the toast provider

Example with all props

<ToastProvider
  class="app-toasts"
  position="top-right"
  duration={4000}
  maxToasts={3}
  ariaLabel="Notifications"
  zIndex={90}
  portal
  data-app-region="toasts"
/>

<!-- Toasts are usually spawned via the global API:
     window.toast.success("Saved!") -->
<Toast
  class="saved-toast"
  id="saved-toast"
  message="Your changes have been saved"
  type="warning"
  dismissible
  dismissLabel="Dismiss notification"
  data-state="ready"
/>