Skip to main content

Toast

A lightweight, accessible toast notification system for showing short, non-blocking feedback messages.
The ToastProvider manages state and timing, while useToast() exposes a simple API to trigger toasts from anywhere in your app.

Usage​

Setup (required)​

Wrap your application (or a subtree) with ToastProvider.

import { ToastProvider } from '@nofinite/nui';

function App() {
  return (
    <ToastProvider>
      <YourApp />
    </ToastProvider>
  );
}

Basic usage with useToast​

import { useToast } from '@nofinite/nui';

function Demo() {
  const toast = useToast();

  return (
    <button onClick={() => toast.show('Profile updated successfully!')}>
      Show Toast
    </button>
  );
}

With custom timeout​

toast.show('Saved with 5s timeout', 5000);

Variants​

Currently, the Toast component does not expose visual variants via props.

  • Styling is theme-driven via CSS variables:

    • --color-bg
    • --color-text
    • --color-text-secondary
    • --color-primary
    • --radius-md

Guidelines:

  • Use toasts for short, informational feedback.
  • Avoid using them for critical blocking errors or confirmations.

Sizes​

No explicit size props are supported.

  • Width is controlled via CSS:

    • min-width: 240px
    • max-width: 320px

You can override sizing using custom CSS if needed.

States​

Auto-dismiss (default)​

  • Toasts automatically disappear after 3000ms by default.

Manual dismiss​

  • Each toast includes a close (×) button.
  • Clicking it immediately removes the toast.

Reduced motion​

  • Animations are disabled when the user prefers reduced motion:
@media (prefers-reduced-motion: reduce) {
  .ui-toast {
    animation: none;
  }
}

Native Props / Composition​

ToastProvider​

  • Accepts children: React.ReactNode
  • Does not forward DOM props (logic-only provider)

Toast (internal)​

The Toast component renders:

  • A semantic alert container
  • A close button with an accessible label
<div className="ui-toast" role="alert">
  <span>{message}</span>
  <button aria-label="Close notification">×</button>
</div>

API​

useToast()​

Returns an object with the following method:

MethodTypeDescription
show(message: string, timeout?: number) => voidDisplays a toast message with optional auto-dismiss timeout

Example​

const toast = useToast();
toast.show('Action completed');
toast.show('Custom timeout', 5000);

Behavior Notes​

  • Toasts are rendered in a Portal, outside the main DOM tree.
  • Multiple toasts can be shown simultaneously.
  • Toast IDs are generated internally.
  • The provider owns all lifecycle logic (add, auto-remove, manual remove).
setTimeout(() => {
  setToasts((prev) => prev.filter((t) => t.id !== id));
}, timeout);

Accessibility​

  • Each toast uses role="alert" for immediate screen reader announcement.

  • Toast container includes:

    • aria-live="polite"
    • aria-atomic="true"

  • Close button includes an explicit aria-label.

<button aria-label="Close notification">×</button>

Layout​

  • Toasts are fixed-positioned in the bottom-right corner.
  • Stacked vertically with spacing.
.ui-toast-container {
  position: fixed;
  bottom: 20px;
  right: 20px;
  display: flex;
  flex-direction: column;
  gap: 12px;
}

Best Practices​

Do​

  • Use for success messages, confirmations, and lightweight feedback.
  • Keep messages short and clear.
  • Wrap your app once with ToastProvider.

Don’t​

  • Use toasts for critical errors that require user action.
  • Overload users with too many toasts at once.
  • Use long, paragraph-style content inside a toast.