Untoastify

Untoastify is a lightweight toast notification library for React.

Installation

npm install untoastify

Provider

Mount the provider once in your app.

import { ToastProvider } from "untoastify";

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

You can also mount it by itself when using the exported toast object.

<>
  <YourApp />
  <ToastProvider />
</>

Usage

import { toast } from "untoastify";

toast.success("Saved successfully");
toast.error("Something went wrong");
toast.info("Heads up");
toast.warning("Check this before continuing");

The hook has the same simple API.

import { useToast } from "untoastify";

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

  return (
    <button onClick={() => toast.success("Saved successfully")}>Save</button>
  );
}

Options

toast.success("Saved successfully", {
  position: "top-right",
  duration: 3000,
  size: "lg",
  className: "my-toast",
  style: { boxShadow: "0 16px 40px rgba(0, 0, 0, 0.18)" },
});

Custom icons

Pass a React icon directly, or pass an imported PNG/image URL.

import { CheckCircle } from "react-icons/fa";
import successPng from "./success.png";

toast.success("React icon", { icon: <CheckCircle /> });
toast.success("Component works too", { icon: CheckCircle });
toast.success("PNG icon", { icon: successPng });
toast.success("No icon", { icon: null });

Set defaults per toast type on the provider:

<ToastProvider icons={{ success: <CheckCircle /> }} />

Stacking and queues

// Default: each toast is placed above or below the previous one.
<ToastProvider stack="list" />

// Toasts overlap with a visible card/deck effect.
<ToastProvider stack="cards" />

// Show one toast at a time and let the others wait.
<ToastProvider stack="overlap" queue="wait" />

// Immediately replace the visible toast with the newest one.
<ToastProvider stack="overlap" queue="replace" />

Top positions grow downward. Bottom positions grow upward.

All toast options

{
  position?: "top-left" | "top-center" | "top-right"
    | "bottom-left" | "bottom-center" | "bottom-right";
  duration?: number;
  size?: "sm" | "md" | "lg" | "xl" | "2xl";
  icon?: React.ReactElement | React.ComponentType
    | string | { src: string; alt?: string } | null | false;
  className?: string;
  style?: React.CSSProperties;
  iconClassName?: string;
  iconStyle?: React.CSSProperties;
  messageClassName?: string;
  messageStyle?: React.CSSProperties;
  closeButtonClassName?: string;
  closeButtonStyle?: React.CSSProperties;
  onClose?: () => void;
}

Every styling parameter is optional. style and className customize the whole toast; iconStyle, messageStyle, and closeButtonStyle target the individual parts. Inline styles override the matching built-in values:

toast.info("Fully custom", {
  position: "bottom-center",
  size: "xl",
  style: {
    width: 420,
    maxWidth: "90vw",
    fontFamily: "Georgia, serif",
    fontSize: 18,
    fontStyle: "italic",
    boxShadow: "0 12px 32px rgba(0, 0, 0, 0.2)",
  },
  messageStyle: {
    color: "white",
    backgroundColor: "#171717",
  },
});

position and size override the provider defaults for a single toast. Use the CSS options for visual values beyond those presets.

Provider-level CSS options apply to every toast, and per-toast options override them.

<ToastProvider
  defaultPosition="top-right"
  defaultDuration={5000}
  defaultSize="md"
  stack="list"
  className="brand-toast"
  messageClassName="brand-toast-message"
/>

Defaults are always available: top-right, 4000ms, md, list, built-in icons, and "Please provide a message" when no message is supplied. Invalid runtime values safely fall back to these defaults.

Development

git clone https://github.com/clouds440/untoastify.git
cd untoastify

License

ISC