Documentation

Getting Started

A beautiful and minimal toast notification library for Astro. Install once, use everywhere — no framework overhead, no opinions.

📦 Installation

Install toastro using your preferred package manager:

# install the package
npm install toastro

🛠️ Setup

Add <Toaster /> once in your main layout. It manages the notification queue and all animations automatically.

src/layouts/Layout.astro
---
import { Toaster } from 'toastro';
---

<html lang="en">
  <body>
    <slot />
    <Toaster />
  </body>
</html>
<Toaster /> defaults to position="bottom-right". See Positions for all options.

⚡ Usage

Call window.showToast() from any client script. No imports needed — it's globally available once <Toaster /> is mounted.

src/pages/index.astro
<button id="btn">Show toast</button>

<script>
  document.getElementById("btn").addEventListener("click", () => {
    window.showToast({
      message: "Hello from toastro 🍞",
      type:    "success",
      variant: "glass",
    });
  });
</script>

🏷️ Types

Use type to convey intent. Each type ships with a built-in icon. 

window.showToast({ message: "Saved!",            type: "success" });
window.showToast({ message: "Something failed",  type: "error"   });
window.showToast({ message: "Watch out",         type: "warning" });
window.showToast({ message: "Just so you know",  type: "info"    });
window.showToast({ message: "Plain message",     type: "default" });
TypeIconUse case
default Neutral messages
success Completed actions
error Failures, validation errors
warning Non-critical alerts
info Informational messages

🎨 Variants

Control the visual style of each toast with variant. 

window.showToast({ message: "Solid",   type: "success", variant: "solid"   });
window.showToast({ message: "Soft",    type: "success", variant: "soft"    });
window.showToast({ message: "Outline", type: "success", variant: "outline" });
window.showToast({ message: "Glass",   type: "success", variant: "glass"   });
VariantDescription
solid Filled background, high contrast default
softSubtle tint, low contrast
outlineTransparent background with colored border
glassFrosted glass effect with backdrop blur

📐 Positions

Pass position to <Toaster /> to control where toasts appear. 

<Toaster position="bottom-right"  />  <!-- default -->
<Toaster position="bottom-left"   />
<Toaster position="bottom-center" />
<Toaster position="top-right"     />
<Toaster position="top-left"      />
<Toaster position="top-center"    />
<Toaster position="center"        />
top-left
top-center
top-right
center
bottom-left
bottom-center
bottom-right
The slide-in animation adapts automatically: left positions slide from the left, right from the right, center positions from below.

✳️ Custom Icons

Pass a raw SVG string to override the default icon, or null to hide it entirely. 

// Custom SVG icon
window.showToast({
  message: "Deployed to production",
  icon: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
  viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
  <path d="M12 19V5M5 12l7-7 7 7"/>
</svg>`,
});

// No icon
window.showToast({
  message: "Clean, iconless toast",
  icon: null,
});

🌈 Custom Colors

Solid color

Use color to set a custom accent that drives the icon, border, and highlights. 

window.showToast({
  message: "Custom brand color",
  color:   "#6366f1",
});

Gradient

Pass an array of colors to gradientColors for a horizontal gradient background. 

window.showToast({
  message:        "Gradient toast 🌈",
  gradientColors: ["#f97316", "#ec4899", "#8b5cf6"],
});

⏱️ Duration

Control how long (in ms) the toast stays visible. Defaults to 4000. 

window.showToast({ message: "Quick!",   duration: 1500 });
window.showToast({ message: "Lingers…", duration: 8000 });

🎨 CSS Theming

Toastro uses CSS variables so it inherits your site's design system automatically. Override any of these in your global styles: 

:root {
  --toastro-bg:     var(--bg);    /* toast background */
  --toastro-text:   var(--text);  /* text color       */
  --toastro-radius: 12px;              /* border radius    */
}

⚙️ API Reference

<Toaster /> props

PropTypeDefaultDescription
position Position "bottom-right" Where toasts appear on screen 
type Position =
  | "top-left"      | "top-center"    | "top-right"
  | "bottom-left"   | "bottom-center" | "bottom-right"
  | "center";

showToast(options)

OptionTypeDefaultDescription
messagestringrequiredThe text content of the toast
typeToastType"default"Controls icon and color theme
variantToastVariant"solid"Visual style
iconstring | nullundefinedCustom SVG string, or null to hide
colorstringundefinedCustom CSS color for the accent
gradientColorsstring[]undefinedArray of colors for gradient background
durationnumber4000Time in ms before auto-dismiss
 
type ToastType    = "default" | "success" | "error" | "warning" | "info";
type ToastVariant = "solid" | "soft" | "outline" | "glass";