How to Use

Toast

Toast shows temporary notifications at the edge of the screen. It requires a ToastProvider at the app root, then you call the toast() function from anywhere to show a notification. Toasts auto-dismiss after a few seconds. Use them for non-intrusive feedback after actions: save confirmations, error alerts, or success messages that don't require user interaction.

import {Toast} from "oks-ui"

Setup Provider

Wrap your application root in ToastProvider once. It manages the toast queue and renders notifications in a fixed position at the edge of the screen. Do not create multiple instances. Place it after your main content wrapper so toasts render above the page content. ToastProvider accepts no props — it is a pure context provider.

// app/layout.tsx — wrap once at the root
import { ToastProvider } from 'oks-ui';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ToastProvider>
          {children}
        </ToastProvider>
      </body>
    </html>
  );
}

Show Toasts

Call toast() with a message string and an optional options object. The color option controls the toast's semantic role: success (green) for confirmations, danger (red) for errors, warning (amber) for cautions. Toast auto-dismisses after a configurable duration (default ~3 seconds). Multiple toasts stack vertically. Call toast() from anywhere in your component tree — event handlers, async callbacks, effects.

import { toast } from 'oks-ui';

function SaveButton() {
  async function handleSave() {
    try {
      await fetch("/api/data", { method: "POST" });
      toast("Saved successfully", { color: "success" });
    } catch {
      toast("Failed to save", { color: "danger" });
    }
  }
  return <Button onClick={handleSave} color="primary">Save</Button>;
}

Accessibility

Toast notifications use role="status" or role="alert" depending on the color. Success and info toasts use role="status" (announced when idle). Error and warning toasts use role="alert" (announced immediately). The toast container uses aria-live="polite" for queued announcements. Toasts are focusable for users who want to interact before dismissal. The dismiss animation respects prefers-reduced-motion.

Props Reference

All available props for Toast. See the full API reference page for interactive playground examples.

Prop	Type	Default	Description
position	"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"	`"top-right"`	Toast stack position.
maxToasts	number	`5`	Maximum visible toasts.
defaultDuration	number	`4000`	Default toast display duration (ms).
disableAnimation	boolean	`false`	Disable toast animations.
toastOffset	number	`12`	Offset between stacked toasts.

Best Practices

◆Wrap your app in ToastProvider once at the root — do not create multiple instances or wrap it in individual pages
◆Use color="success" for positive feedback (save, create, update), color="danger" for errors, color="warning" for cautions
◆Toasts auto-dismiss — do not use them for critical information that must be seen (use Alert for that)
◆Toasts stack vertically when multiple are shown at once — newest appears at the top by default
◆Call toast() directly in event handlers — no need for useState or context
◆For complex notification content (links, buttons), use Alert inside a custom toast implementation instead

View full API reference for Toast →