Toast component

Playground

Change a prop on the right and the preview updates. Switch to Code to copy what you see.

Recipes

Copy-paste patterns for the ways Toast actually gets used — each one a real, self-contained example.

// app root
<ToastProvider>
  <App />
</ToastProvider>

// anywhere
import { toast } from "oks-ui/toast";

toast.success("Saved");
toast.error("Upload failed");
toast.warning("Storage almost full");
toast.info("A new version is available");

toast.success("Profile updated", {
  description: "Your changes are visible to your team.",
});

toast("Message archived", {
  action: { label: "Undo", onClick: () => restore() },
  duration: null,
});

toast.promise(saveProfile(data), {
  loading: { message: "Saving…" },
  success: () => ({ message: "Profile saved" }),
  error: () => ({ message: "Couldn't save profile" }),
});

toast.error("Payment failed", {
  description: "Update your card to keep your subscription.",
  persistent: true,
  dismissible: true,
});

One provider, called from anywhere

Mount ToastProvider once, high in the tree — it renders a portaled region (position defaults to bottom-right) that every toast() call anywhere in the app renders into. There's no toast context to consume and no hook to call at the use-site; toast(...) is a plain imported function.

// app root
<ToastProvider position="top-right" maxVisibleToasts={3}>
  <App />
</ToastProvider>

// anywhere else in the tree
import { toast } from "oks-ui";

const SaveButton = () => {
  return (
    <Button onPress={() => toast.success("Saved", { description: "Your changes were saved." })}>
      Save
    </Button>
  );
};

Typed shortcuts and full control

toast.success/toast.error/toast.warning/toast.info are shortcuts that set both type and the matching default icon. For anything not covered by a shortcut, call toast(options) directly with the full ToastOptions shape — variant, size, duration, a dismiss/action button, whatever you need.

toast.success("Copied to clipboard");
toast.error("Upload failed", { description: "The file exceeded 10 MB.", persistent: true });

toast({
  title: "Update available",
  description: "A new version is ready to install.",
  action: { label: "Reload", onClick: () => window.location.reload() },
  duration: null,
});

Promise-aware toasts

Pass a promise and toast walks through loading → success/error on its own — no manual success()/error() calls to keep in sync with the actual request. It shows a loading state immediately, then swaps to success or error once the promise settles.

toast.promise(saveProfile(formData), {
  loading: "Saving…",
  success: "Profile saved",
  error: "Couldn't save profile",
});

Duration, persistence, and dismissal

Every toast auto-dismisses after defaultDuration (6s) unless you override duration per-toast, or set persistent to remove the auto-dismiss timer entirely (typically paired with dismissible so the user still has a way to close it manually). showDurationBar renders a shrinking progress bar so the countdown is visible, not just implied.

toast.warning("Session expiring soon", { duration: 10000, showDurationBar: true });
toast.error("Payment failed", { persistent: true, dismissible: true });

Props

The full public API for Toast. Every prop is stable and intentionally typed.

Accessibility

• •The toast region is a live region, so screen readers announce new toasts as they appear without the user needing to navigate to them.
• •When dismissible (the default), the close button is a real, keyboard-operable button with its own accessible name.
• •Prefer persistent + a visible action for anything the user actually needs to act on — an auto-dismissing toast that disappears before it's read defeats its own purpose for anyone reading slowly or using a screen reader.

Best practices

• ◆Keep toast text to one short sentence; if a message needs a paragraph of explanation, it probably belongs in an inline Alert instead.
• ◆Reserve persistent for toasts the user must act on (a failed payment, a required re-auth) — persistent success confirmations just pile up.
• ◆Use toast.promise for anything already returning a promise (a save, an upload, a fetch) instead of manually calling toast.success/toast.error in a .then()/.catch() — it keeps the loading state honest.
• ◆Only one ToastProvider is meant to be mounted per toast "queue" — nesting multiple providers doesn't give you independent queues, since toast() targets whichever provider is currently mounted.
• ◆For a message tied to specific content on the page (a form field error, a section-level warning), use Alert instead — Toast is for transient, page-level notifications, not content that should stay anchored in the layout.