useToast()

The useToast() composable is the main API for creating and managing toast notifications.

Import

<script setup>
const toast = useToast();
</script>

Methods

`toast.success(title, description?, options?)`

Display a success toast.

Parameters:

title (string) — toast title
description (string, optional) — toast description
options (object, optional) — additional options

Success

<script setup>
const toast = useToast();

toast.success("Saved", "Your changes were saved");
</script>

`toast.error(title, description?, options?)`

Display an error toast.

Parameters:

title (string)
description (string, optional)
options (object, optional)

Error

<script setup>
const toast = useToast();

toast.error("Error", "Something went wrong");
</script>

`toast.info(title, description?, options?)`

Display an info toast.

Parameters:

title (string)
description (string, optional)
options (object, optional)

Info

<script setup>
const toast = useToast();

toast.info("Update Available", "A new version is ready");
</script>

`toast.warning(title, description?, options?)`

Display a warning toast.

Parameters:

title (string)
description (string, optional)
options (object, optional)

Warning

<script setup>
const toast = useToast();

toast.warning("Warning", "This action cannot be undone");
</script>

`toast.add(options)`

Create a toast with full customization.

Parameters:

options (ToastOptions) — complete toast configuration object

add()

<script setup>
const toast = useToast();

toast.add({
  type: "success",
  title: "Welcome",
  description: "Thanks for signing up!",
  duration: 5000,
  showProgress: true,
  actions: [
    {
      label: "Get Started",
      onClick: () => {
        console.log("Started");
      },
    },
  ],
});
</script>

`toast.clear()`

Remove all visible toasts immediately.

clear()

<script setup>
const toast = useToast();

toast.success("Toast 1");
toast.info("Toast 2");

// Clear all toasts
toast.clear();
</script>

Usage examples

Basic usage

Basic

<script setup>
const toast = useToast()

function handleSave() {
  try {
    // Save logic...
    toast.success("Saved successfully")
  } catch (error: any) {
    toast.error("Save failed", error?.message || "Unknown error")
  }
}
</script>

<template>
  <button
    class="rounded-lg bg-primary-500 px-4 py-2 text-sm font-semibold text-gray-950"
    @click="handleSave"
  >
    Save
  </button>
</template>

With async operations

Async

<script setup>
const toast = useToast()

async function uploadFile(file: File) {
  // Optional: show a quick info toast
  toast.info("Uploading...", file.name, { duration: 2000 })

  try {
    // await api.upload(file)
    await new Promise((r) => setTimeout(r, 900))

    toast.success("Uploaded", `${file.name} uploaded successfully`)
  } catch (error: any) {
    toast.error("Upload failed", error?.message || "Unknown error")
  }
}
</script>

Progressive enhancement

Steps

<script setup>
const toast = useToast();

function showProgressSteps() {
  let step = 1;
  const max = 3;

  const interval = window.setInterval(() => {
    if (step <= max) {
      toast.info(`Step ${step}`, `Processing step ${step} of ${max}`);
      step++;
    } else {
      window.clearInterval(interval);
      toast.success("Complete!", "All steps finished");
    }
  }, 2000);
}
</script>