Nuxt

toast vs useToast()

When to call the auto-imported toast object and when the useToast composable is a better fit for showing notifications in Nuxt apps.

Both are auto-imported by nuxt-toastflow. They point to the same Toastflow runtime.

Use toast

Best for one-off calls in pages, click handlers, composables, and callbacks.

Use useToast()

Best when you want to name the API once and pass it around explicitly.

Side By Side

toast.success({
  title: "Saved",
});

const toastApi = useToast();

toastApi.success({
  title: "Saved",
});

Same Store

same-store.ts

const toastApi = useToast();

toastApi.dismissAll();
toast.dismissAll();

Both calls operate on the same queue, timers, subscriptions, and visible toasts.

Common Nuxt Patterns

components/CopyLink.vue

<script setup lang="ts">
function copyLink() {
  toast.success({ title: "Copied" });
}
</script>

<template>
  <UButton @click="copyLink">Copy link</UButton>
</template>

composables/useSaveProfile.ts

export function useSaveProfile() {
  const toastApi = useToast();

  return async function saveProfile(payload: unknown) {
    await toastApi.loading(
      $fetch("/api/profile", { method: "POST", body: payload }),
      {
        loading: { title: "Saving profile" },
        success: { title: "Profile saved" },
        error: { title: "Save failed" },
      },
    );
  };
}

update-by-id.ts

const id = toast.show({
  type: "loading",
  title: "Uploading",
  duration: 0,
});

toast.update(id, {
  type: "success",
  title: "Upload complete",
  duration: 3000,
});

Client-Side Rule

Do not call toast or useToast() from Nitro routes, server handlers, route middleware that only runs on the server, or SSR-only code. Toasts are UI feedback, so trigger them from client execution.

Calls that still happen before the client plugin is ready (for example during SSR in shared code) are safe no-ops instead of crashes — method calls do nothing and return undefined, and dev mode logs a warning naming the ignored call.

Quick Decision

Edit this pageorReport an issue

Quick Start

Install the nuxt-toastflow module, configure it in nuxt.config, and show your first toast notification in a Nuxt 3 or Nuxt 4 app.

Module Options

Configure nuxt-toastflow module options such as config defaults, CSS injection, and component naming directly in nuxt.config.