@tehsin06/toast

Reusable React toast notification package with:

• multiple placements (top-right, bottom-left, etc.)
• variants (info, success, warning, error, question)
• action buttons
• auto-dismiss with pause on hover
• smooth enter/exit/cascade animations
• CSS variable based theming

Installation

npm i @tehsin06/toast

Peer dependencies:

• react >= 17
• react-dom >= 17

Quick Start

import React from "react";
import { ToastProvider, ToastViewport, useToast } from "@tehsin06/toast";

function Demo() {
  const { showToast } = useToast();

  return (
    <button
      onClick={() =>
        showToast({
          title: "Saved",
          message: "Your changes were saved successfully.",
          variant: "success",
        })
      }
    >
      Show toast
    </button>
  );
}

export default function App() {
  return (
    <ToastProvider>
      <Demo />
      <ToastViewport />
    </ToastProvider>
  );
}

Exports

import {
  ToastProvider,
  ToastViewport,
  useToast,
  type ShowToastInput,
  type ToastAction,
  type ToastColorOverrides,
  type ToastExitAnimation,
  type ToastPlacement,
  type ToastShape,
  type ToastStackInsert,
  type ToastThemePalette,
  type ToastVariant,
} from "@tehsin06/toast";

API

ToastProvider

Context provider that stores toasts and exposes the toast controller methods through useToast().

useToast()

Returns:

• toasts
• showToast(toast)
• setToastDefaults(defaults | null)
• dismissToast(id, reason?, exitAnimation?)
• pauseToastAutoDismiss(id)
• resumeToastAutoDismiss(id)
• clearToasts()

showToast(input: ShowToastInput)

Common options:

• title (required unless provided through viewport defaults)
• message
• variant: info | success | warning | error | question
• placement: top-right | top-left | top-center | bottom-right | bottom-left | bottom-center
• durationMs (default: 3600)
• dismissible (default: true)
• poppable (click toast to dismiss, default: true)
• stackInsert: front | end
• appearDelayMs
• animation_appear (default: true)
• animation_cascade (default: true)
• exitAnimation: fade | pop
• style options: width, minHeight, padding, shape, borderRadius, titleFontSize, bodyFontSize
• actions: ToastAction[]
• colorOverrides: ToastColorOverrides
• callbacks: onClick(toast), onAction(actionId, toast)

ToastViewport

Props:

• topOffset, rightOffset, bottomOffset, leftOffset
• maxStackWidth (default 420)
• zIndex (default 2000)
• default toast values: placement, type, title, message, durationMs
• shadow

Use placement to force a single viewport location, or omit it to render all placements.

Action Buttons Example

showToast({
  title: "Item deleted",
  message: "You can undo this action.",
  variant: "warning",
  actions: [
    {
      id: "undo",
      label: "Undo",
      tone: "primary",
      onPress: () => console.log("Undo clicked"),
    },
  ],
  onAction: (actionId) => {
    if (actionId === "undo") {
      console.log("Undo from onAction");
    }
  },
});

Styling & Theme

The package includes default styles and CSS variables. You can override them in your app:

:root {
  --color-toast-success-bg: #0f3f2d;
  --color-toast-success-border: #34d399;
  --color-toast-success-text: #ecfdf5;
  --color-toast-success-icon: #34d399;

  --color-toast-info-bg: #0f294b;
  --color-toast-info-border: #60a5fa;
  --color-toast-info-text: #eff6ff;
  --color-toast-info-icon: #60a5fa;

  --color-toast-warning-bg: #4a300b;
  --color-toast-warning-border: #fbbf24;
  --color-toast-warning-text: #fffbeb;
  --color-toast-warning-icon: #fbbf24;

  --color-toast-error-bg: #571c1c;
  --color-toast-error-border: #f87171;
  --color-toast-error-text: #fef2f2;
  --color-toast-error-icon: #f87171;

  --color-toast-question-bg: #37235d;
  --color-toast-question-border: #a78bfa;
  --color-toast-question-text: #f5f3ff;
  --color-toast-question-icon: #a78bfa;

  --shadow-toast: 0 10px 24px rgba(0, 0, 0, 0.28);
}

If you want to import styles explicitly:

import "@tehsin06/toast/toast.css";

License

MIT