On this page

Toast

---
import { Button } from "@/components/starwind/button";
---

<div class="flex flex-wrap gap-2">
  <Button variant="outline" id="toast-demo-default">Default</Button>
  <Button variant="outline" id="toast-demo-success">Success</Button>
  <Button variant="outline" id="toast-demo-error">Error</Button>
</div>

<script>
  import { toast } from "@starwind-ui/astro/toast";

  document.getElementById("toast-demo-default")?.addEventListener("click", () => {
    toast("Default Toast");
  });

  document.getElementById("toast-demo-success")?.addEventListener("click", () => {
    toast.success("Success!", { description: "Your changes have been saved." });
  });

  document.getElementById("toast-demo-error")?.addEventListener("click", () => {
    toast.error("Error", { description: "Something went wrong." });
  });
</script>

import { Button } from "@/components/starwind/button";
import { toast } from "@starwind-ui/react/toast";

export function Example() {
  return (
    <div className="flex flex-wrap gap-2">
      <Button variant="outline" onClick={() => toast("Default Toast")}>Default</Button>
      <Button variant="outline" onClick={() => toast.success("Success!", { description: "Your changes have been saved." })}>Success</Button>
      <Button variant="outline" onClick={() => toast.error("Error", { description: "Something went wrong." })}>Error</Button>
    </div>
  );
}

Runtime adjustment

The styled package supplies the Toaster markup, while imperative notifications now come from the framework primitive entrypoint: @starwind-ui/astro/toast.

Installation

pnpx starwind@latest add toast

npx starwind@latest add toast

yarn dlx starwind@latest add toast

Usage

Setup

The Toaster component must be added once to your page, usually in a common layout file shared between pages so you can trigger toasts from anywhere.

---
import { Toaster } from "@/components/starwind/toast";
---

<!doctype html>
<html lang="en">
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- navigation -->
    <main>
      <!-- content -->
    </main>
    <Toaster position="bottom-right" />
  </body>
</html>

Basic Usage

Toasts are created using the toast function. Import it in a <script> tag and call it to show notifications.

<Button id="show-toast">Show Toast</Button>

<script>
  import { toast } from "@starwind-ui/astro/toast";

  document.getElementById("show-toast")?.addEventListener("click", () => {
    toast("Hello world!");
  });
</script>

import { Button } from "@/components/starwind/button";
import { toast } from "@starwind-ui/react/toast";

export function Example() {
  return <Button onClick={() => toast("Hello world!")}>Show Toast</Button>;
}

Variants

The toast system supports multiple variants for different message types.

---
import { Button } from "@/components/starwind/button";
---

<div class="flex flex-wrap gap-2">
  <Button variant="outline" id="toast-default">Default</Button>
  <Button variant="outline" id="toast-success">Success</Button>
  <Button variant="outline" id="toast-error">Error</Button>
  <Button variant="outline" id="toast-warning">Warning</Button>
  <Button variant="outline" id="toast-info">Info</Button>
  <Button variant="outline" id="toast-loading">Loading</Button>
</div>

<script>
  import { toast } from "@starwind-ui/astro/toast";

  document.getElementById("toast-default")?.addEventListener("click", () => {
    toast("Default Toast");
  });

  document.getElementById("toast-success")?.addEventListener("click", () => {
    toast.success("Success!", {
      description: "Your changes have been saved.",
    });
  });

  document.getElementById("toast-error")?.addEventListener("click", () => {
    toast.error("Error", {
      description: "Something went wrong.",
    });
  });

  document.getElementById("toast-warning")?.addEventListener("click", () => {
    toast.warning("Warning", {
      description: "Please review your input.",
    });
  });

  document.getElementById("toast-info")?.addEventListener("click", () => {
    toast.info("Info", {
      description: "Here's some helpful information.",
    });
  });

  document.getElementById("toast-loading")?.addEventListener("click", () => {
    toast.loading("Loading...", {
      description: "Please wait while we process your request.",
    });
  });
</script>

import { Button } from "@/components/starwind/button";
import { toast } from "@starwind-ui/react/toast";

export function Example() {
  return (
    <div className="flex flex-wrap gap-2">
      <Button variant="outline" onClick={() => toast("Default Toast")}>Default</Button>
      <Button
        variant="outline"
        onClick={() => toast.success("Success!", { description: "Your changes have been saved." })}
      >
        Success
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.error("Error", { description: "Something went wrong." })}
      >
        Error
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.warning("Warning", { description: "Please review your input." })}
      >
        Warning
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.info("Info", { description: "Here's some helpful information." })}
      >
        Info
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.loading("Loading...", { description: "Please wait while we process your request." })}
      >
        Loading
      </Button>
    </div>
  );
}

Promise Toast

Handle async operations with automatic loading, success, and error states.

---
import { Button } from "@/components/starwind/button";
---

<div class="flex flex-wrap gap-2">
  <Button variant="primary" id="toast-promise-success">Promise (Success)</Button>
  <Button variant="error" id="toast-promise-error">Promise (Error)</Button>
</div>

<script>
  import { toast } from "@starwind-ui/astro/toast";

  document.getElementById("toast-promise-success")?.addEventListener("click", () => {
    const fakeApiCall = async () => {
      await new Promise((resolve) => setTimeout(resolve, 2000));
      return { name: "John" };
    };

    toast.promise(fakeApiCall(), {
      loading: { title: "Saving...", description: "Please wait" },
      success: (data) => ({ title: "Saved!", description: `Welcome, ${data.name}!` }),
      error: { title: "Error", description: "Failed to save" },
    });
  });

  document.getElementById("toast-promise-error")?.addEventListener("click", () => {
    const fakeApiCall = async () => {
      await new Promise((resolve) => setTimeout(resolve, 2000));
      throw new Error("Network error");
    };

    toast
      .promise(fakeApiCall(), {
        loading: "Processing...",
        success: "Done!",
        error: (err) => ({
          title: err.message || "Contact support for assistance",
          description: "Pardon our dust while we fix this issue.",
        }),
      })
      .catch(() => {});
  });
</script>

import { Button } from "@/components/starwind/button";
import { toast } from "@starwind-ui/react/toast";

async function successfulRequest() {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  return { name: "John" };
}

async function failedRequest() {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  throw new Error("Network error");
}

export function Example() {
  return (
    <div className="flex flex-wrap gap-2">
      <Button
        variant="primary"
        onClick={() => {
          void toast.promise(successfulRequest(), {
            loading: { title: "Saving...", description: "Please wait" },
            success: (data) => ({ title: "Saved!", description: "Welcome, " + data.name + "!" }),
            error: { title: "Error", description: "Failed to save" },
          });
        }}
      >
        Promise (Success)
      </Button>
      <Button
        variant="error"
        onClick={() => {
          void toast
            .promise(failedRequest(), {
              loading: "Processing...",
              success: "Done!",
              error: (error) => ({
                title: error instanceof Error ? error.message : "Contact support for assistance",
                description: "Pardon our dust while we fix this issue.",
              }),
            })
            .catch(() => {});
        }}
      >
        Promise (Error)
      </Button>
    </div>
  );
}

Updating & Dismissing

You can update existing toasts or dismiss them programmatically.

---
import { Button } from "@/components/starwind/button";
---

<div class="flex flex-wrap gap-2">
  <Button variant="outline" id="toast-update">Create & Update</Button>
  <Button variant="outline" id="toast-dismiss-all">Dismiss All</Button>
</div>

<script>
  import { toast } from "@starwind-ui/astro/toast";

  document.getElementById("toast-update")?.addEventListener("click", () => {
    const id = toast("Processing...", { description: "Step 1 of 3" });

    setTimeout(() => {
      toast.update(id, { title: "Still working...", description: "Step 2 of 3" });
    }, 1500);

    setTimeout(() => {
      toast.update(id, {
        title: "Complete!",
        description: "All steps finished",
        variant: "success",
      });
    }, 3000);
  });

  document.getElementById("toast-dismiss-all")?.addEventListener("click", () => {
    toast.dismiss();
  });
</script>

import { Button } from "@/components/starwind/button";
import { toast } from "@starwind-ui/react/toast";

function createAndUpdateToast() {
  const id = toast("Processing...", { description: "Step 1 of 3" });
  setTimeout(() => {
    toast.update(id, { title: "Still working...", description: "Step 2 of 3" });
  }, 1500);
  setTimeout(() => {
    toast.update(id, {
      title: "Complete!",
      description: "All steps finished",
      variant: "success",
    });
  }, 3000);
}

export function Example() {
  return (
    <div className="flex flex-wrap gap-2">
      <Button variant="outline" onClick={createAndUpdateToast}>Create & Update</Button>
      <Button variant="outline" onClick={() => toast.dismiss()}>Dismiss All</Button>
    </div>
  );
}

API Reference

Styled Component API

These props are added or materially changed by the installed styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. Follow the Primitive and Runtime links for lower-level behavior props.

Toast

Inherits div attributes.

Contains the following additional props:

Prop Type Default

gap string "0.5rem"

Description: Sets the space between repeated items.
Classification: Wrapper prop

peek string "1rem"

Description: Sets how much of an adjacent item remains visible.
Classification: Wrapper prop

Toast Item

Inherits div attributes.

Contains the following additional props:

Prop Type Default

variant "default" | "success" | "error" | "warning" | "info" "default"

Description: Selects the component's visual variant.
Classification: Styled variant

Toast Title

Inherits div attributes.

Contains the following additional props:

Prop Type Default

Description: Selects the component's visual variant.
Classification: Styled variant

Toast Close

Inherits button attributes.

Contains the following additional props:

Prop Type Default

showIcon boolean true

Description: Shows the component's generated icon.
Classification: Wrapper prop

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Toast.

Primitive API

Toast Primitive

Runtime API

Toast primitive: createToastManager from @starwind-ui/runtime/toast

Changelog

v2.0.1

Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

v2.0.0

Rebuilt Toast on Starwind Runtime for manager state, templates, updates, dismissal, and lifecycle.
See the Toast Primitive for the underlying unstyled anatomy and behavior API.
The styled package supplies the Toaster markup, while imperative notifications now come from the framework primitive entrypoint: @starwind-ui/astro/toast.