Toaster

Installation

npx gbs-add-block@latest -a Toaster -beta

The block copies the toaster folder into your project, along with the small shared folder that every component imports. You own the code and can change it freely. There are no peer dependencies other than React.

Requirements

• React 19 and @types/react 19
• TypeScript target ES2022 or newer, with "jsx": "react-jsx"
• Browsers from 2024 or newer (the styles use light-dark(), :is() and @starting-style)

Import the stylesheet once, for example in your global CSS:

@import "../components/toaster/styles.css";

or in your root layout / entry file:

import "@/components/toaster/styles.css";

The Toaster shows short notifications — saved, failed, undo, in progress — in a corner of the screen. It works in any React app: Vite, Next.js, Remix or plain React. You mount <Toaster /> once and call toast() from anywhere: a component, an event handler, a data layer, or code outside React. There is no hook, context or provider to set up.

Default

Quick Start

1. Mount the Toaster once, near the root of the app:

// Vite / plain React: App.tsx
import { Toaster } from "@/components/toaster";
 
export default function App() {
  return (
    <>
      <Routes />
      <Toaster />
    </>
  );
}

2. Call toast() anywhere:

"use client";
 
import { toast } from "@/components/toaster";
 
export function SaveButton() {
  return <button onClick={() => toast.success("Settings saved")}>Save</button>;
}

Props Table

Toaster

Toast options

The second argument of every toast() call.

Toast Types

toast("Event created", { description: "Monday at 10:00" });
toast.success("Settings saved");
toast.error("Payment declined", { description: "The card was refused." });
toast.warning("Storage almost full");
toast.info("A new version is available");
toast.loading("Syncing…");

Each type sets the icon and the colored bar on the toast's leading edge. Loading toasts stay until you update or dismiss them.

Actions

toast("Message archived", {
  action: { label: "Undo", onClick: () => restoreMessage(id) },
});
 
toast.error("Could not connect", {
  duration: Infinity,
  cancel: { label: "Dismiss", onClick: () => {} },
  action: {
    label: "Retry",
    onClick: (event) => {
      event.preventDefault(); // keep this toast open
      reconnect();
    },
  },
});

Clicking an action or cancel button closes the toast, unless the handler calls event.preventDefault().

Promises

toast.promise shows a loading toast and turns it into a success or error when the promise settles. It returns the same promise, so you can still await it.

const user = await toast.promise(saveUser(data), {
  loading: "Saving…",
  success: (user) => `${user.name} saved`,
  error: (error) => `Could not save: ${(error as Error).message}`,
});

• Pass a promise, or a function that returns one: toast.promise(() => fetch(url), …).
• Leave out success or error to close the toast quietly in that case.
• A rejection is still passed on to the caller, and it is never reported as unhandled.

Updating a Toast

Every call returns an id. Use it to change the toast in place:

const id = toast.loading("Uploading report.pdf", { description: "0%" });
 
toast.update(id, { description: "60%" });
toast.update(id, {
  type: "success",
  title: "report.pdf uploaded",
  description: "2.4 MB",
});

• Changing type without a duration gives the toast that type's default, so a loading toast that becomes a success closes on its own.
• Updating restarts the countdown.
• Calling toast(…, { id }) with an id already on screen does the same as update. This is handy for events that repeat, such as "Offline", which should not stack.

Custom Toasts

toast.custom(
  ({ dismiss }) => (
    <div className="flex items-center gap-3">
      <Avatar user={user} />
      <div className="flex-1">
        <strong>{user.name}</strong> invited you to “Q3 planning”
      </div>
      <button onClick={dismiss}>View</button>
    </div>
  ),
  { duration: 8000 },
);

A custom toast keeps the frame, timing, swipe, Escape and close button; you provide the content.

Calling from Outside React

toast() is a plain function, so it works where hooks cannot:

// api/client.ts
import { toast } from "@/components/toaster";
 
export async function request(url: string) {
  const response = await fetch(url);
  if (!response.ok)
    toast.error("Request failed", { description: `${response.status} ${url}` });
  return response;
}

The same goes for Redux thunks, Zustand actions, TanStack Query onError callbacks and WebSocket handlers.

Multiple Toasters

The ready-made toast shares one store with every <Toaster /> that has no store prop. For a separate notification area, for example inside an embedded widget, create your own:

import {
  createToastApi,
  createToastStore,
  Toaster,
} from "@/components/toaster";
 
const widgetStore = createToastStore({ limit: 1 });
export const widgetToast = createToastApi(widgetStore);
 
<Toaster store={widgetStore} position="bottom-center" />;

Timing and Queueing

• Pausing: timers pause while the pointer is over the toasts, while keyboard focus is inside them, and while the browser tab is hidden. They continue with the time that was left.
• Queueing: only limit toasts are on screen. Newer toasts appear first, and older ones wait with their full time until a slot frees up.
• Order: the newest toast sits nearest the screen edge, at the top for top-* positions and at the bottom for bottom-*.
• Layering: toasts render in a portal on <body> with a very high z-index, so no parent's overflow, transform or stacking context can hide them.

The toast() API

Keyboard

Accessibility: the notifications are a labelled landmark ("Notifications (Alt+T)"). The list is a polite live region that is always in the page, so new toasts are read out without interrupting the user. Error toasts use role="alert" and interrupt. Moving focus into the notifications pauses the timers, so there is time to reach an action.

Styling and Theming

All rules are in the CSS components layer, so utility classes passed through className / classNames override them.

<Toaster
  classNames={{
    toast: "shadow-xl",
    title: "tracking-tight",
    action: "uppercase",
  }}
/>

CSS variables

Override them on .ts-region, on :root, or through style. Each variable falls back to the shared --gbs-* of the same name, then to the DataGrid's --dg-* when that stylesheet is loaded, and finally to the built-in palette.

.ts-region {
  --ts-width: 420px;
  --ts-success: #059669;
  --ts-radius: 12px;
}

Dark mode

Colors follow the page's color-scheme. To force a scheme, put class="dark" or data-theme="dark" (or "light") on an ancestor such as <html>.

Data attributes

Toasts fade and slide in with @starting-style, and fade out while data-state="closing". With prefers-reduced-motion, they appear and disappear without movement.

Locale Text

<Toaster
  localeText={{
    regionLabel: (hotkey) => `Benachrichtigungen (${hotkey})`,
    close: "Schließen",
  }}
/>

Titles, descriptions and button labels are whatever you pass to toast().

Headless Use

useToasts(store?) returns the live snapshot for building a different notification UI on the same store:

const { toasts, paused, limit } = useToasts();
const shown = visibleToasts({ toasts, paused, limit });

The framework-free core is exported from @/components/toaster/core:

A store's snapshots never change once created, so it works directly with useSyncExternalStore, and the timers can be tested with fake timers and no DOM.

Next.js

Mount the Toaster in the root layout. It is a client component, and a Server Component layout can render it directly:

// app/layout.tsx
import { Toaster } from "@/components/toaster";
import "@/components/toaster/styles.css";
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Toaster />
      </body>
    </html>
  );
}

toast() does nothing on the server, because nobody there can see a toast. This also keeps one request's toasts from leaking into another's. To report a Server Action's result, call toast in the client:

"use client";
 
import { toast } from "@/components/toaster";
import { saveProfile } from "./actions";
 
export function ProfileForm() {
  return (
    <form
      action={(formData) => {
        toast.promise(saveProfile(formData), {
          loading: "Saving…",
          success: "Profile saved",
          error: "Could not save your profile",
        });
      }}
    >
      …
    </form>
  );
}

The Toaster renders nothing during the server render and hydration, then mounts its portal, so it never causes a hydration mismatch.

Migrating from the Previous Toast

Notes

• Toasts stack as a list; they do not collapse into an expandable pile.
• toast() only shows toasts in the browser. Call it after a server response arrives, not in server code.
• One shared store means one import path: don't mix @/components/toaster with a relative path to the same files.