ToastProvider

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";

function 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 });

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.

Props reference

All available props for ToastProvider. See the full component page for an interactive playground.

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.