ToastProvider
Feedback

ToastProvider

Manages toast ordering, timers, and placement. Requires a ThemeProvider ancestor.

Preview

ToastProvider

Props

ToastProvider renders its children and a portaled toast viewport.

ToastProviderProps props
PropTypeDefaultDescription
childrenReactNode—App content (wraps the component tree).
placementToastPlacement"bottom-right""top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right".
durationnumber5000Default auto-dismiss in ms. 0 or Infinity makes toasts sticky.
limitnumber4Maximum visible toast count. Exceeding the limit dismisses the oldest toast.

ToastOptions

The object passed to toast():

ToastOptions props
PropTypeDefaultDescription
idstring—Toast ID. Reusing the ID updates the existing toast.
childrenReactNode—Toast message content.
toneToastTone"ok""ok" | "warn" | "err".
hrefstring—Makes the link label clickable.
linkLabelstring—Link text when href is provided.
durationnumber—Per-toast override of the provider's duration.
onDismiss() => void—Called once the toast leaves.

useToast()

useToast() returns an object with toast, dismiss, and toasts.

useToast() return value props
PropTypeDefaultDescription
toastToastFn—Fire a toast. Also has .ok(), .warn(), .err() shorthands.
dismiss(id?: string) => void—Dismiss one toast by id, or all when called with no id.
toastsToastRecord[]—Current toast records.

Examples

Basic setup

ImportTSX
import {
  ThemeProvider,
  ToastProvider,
  useToast,
  Button,
} from "@solarius/onset";

// Wrap your app
function App() {
  return (
    <ThemeProvider>
      <ToastProvider placement="bottom-right" duration={5000}>
        <SaveButton />
      </ToastProvider>
    </ThemeProvider>
  );
}

// Fire from anywhere below
function SaveButton() {
  const { toast } = useToast();

  return (
    <Button
      onClick={() => {
        toast("Changes saved");
        // or with options:
        toast({ children: "Changes saved", tone: "ok" });
        // or using shorthands:
        toast.ok("Deployment started");
        toast.warn("Storage at 85%");
        toast.err("Save failed — retry");
      }}
    >
      Save
    </Button>
  );
}

Idempotent toasts

Idempotent keyTSX
const { toast } = useToast();

function save() {
  const id = toast({ id: "save", children: "Saving…", tone: "ok" });
  // Later, update in place rather than stacking a second card:
  toast({ id: "save", children: "Saved", tone: "ok" });
}

Dismiss toasts

DismissTSX
const { toast, dismiss } = useToast();

// Dismiss one
const id = toast("Loading…");
dismiss(id);

// Dismiss all
dismiss();

Custom placement and duration

Provider configTSX
<ToastProvider placement="top-right" duration={3000} limit={3}>
  <App />
</ToastProvider>