Toastly UI

A fully customizable, lightweight, and production-ready toast notification library for React application. Designed for simplicity and performance with modern design systems in mind.

✨ View Live Demo   |   📦 View on NPM

---

Table of Contents

• Introduction
• Features
• Installation
• Getting Started
• Usage
  • Basic Toasts
  • Promise Handling
  • Custom Component
• API Reference
• Styling & Customization
• License

Introduction

Toastly UI creates a seamless notification experience for your users. Unlike other libraries that feel heavy or complex, Toastly UI focuses on providing a clean API with beautiful "Glassmorphism" aesthetics out of the box. It uses a centralized store observer pattern, meaning you can trigger toasts from anywhere in your application without context wrapping hell.

Features

• Lightweight: Less than 5kb gzipped. Zero external UI dependencies.
• Headless-ish: Full control over styling using CSS variables or custom classes.
• Smart Positioning: Supports 6 different screen positions (Top/Bottom - Left/Center/Right).
• Promise Support: Native support for handling asynchronous operations (Loading -> Success/Error).
• Multiple Variants: Includes Modern, Minimalist, Enterprise, and Glass styles.
• Accessible: WAI-ARIA compliant for screen readers.
• TypeScript: Written in TypeScript with complete type definitions included.

Installation

Install the package via your preferred package manager:

npm install toastly-ui

Or using Yarn:

yarn add toastly-ui

Getting Started

To start using Toastly UI, you need to add the Toaster component to the root of your application. This component acts as the container for all your notifications.

1. Import the Component and Styles

In your root file (e.g., App.tsx, layout.tsx, or main.tsx):

import { Toaster } from 'toastly-ui';
import 'toastly-ui/dist/toastly.css'; // Essential for styling

export default function App() {
  return (
    <>
      {/* Your application components */}
      <Toaster position="top-right" />
    </>
  );
}

Usage

You can trigger notifications from anywhere in your app using the toast object.

Basic Toasts

import { toast } from 'toastly-ui';

// Success message
toast.success('Your changes have been saved.');

// Error message
toast.error('Unable to connect to the server.');

// Info message
toast.info('New update available.');

// Custom options
toast.success('Profile Updated', {
  duration: 5000,
  position: 'bottom-center',
  variant: 'glass'
});

Promise Handling

The toast.promise function automatically handles the loading state and updates the toast to success or error based on the promise resolution.

const handleSave = async () => {
  const myPromise = saveDataToDatabase();

  toast.promise(myPromise, {
    loading: 'Saving data...',
    success: 'Data saved successfully!',
    error: 'Could not save data.'
  });
};

You can also use functions to generate dynamic messages based on the response:

toast.promise(fetchUser(), {
  loading: 'Loading user...',
  success: (data) => `Welcome back, ${data.name}!`,
  error: (err) => `Login failed: ${err.message}`
});

API Reference

Toaster Props

The <Toaster /> component accepts the following props:

Prop	Type	Default	Description
position	string	'top-right'	Where the toasts appear. Options: top-left, top-right, top-center, bottom-left, bottom-right, bottom-center.
toastOptions	object	{}	Default options applied to all toasts (e.g., variant, style, className).

Toast Options

These options can be passed to any toast() call:

Option	Type	Description
duration	number	Time in milliseconds before auto-dismiss. Default is 3000ms.
variant	string	Visual style. Options: modern, minimalist, enterprise, glass.
icon	ReactNode	Custom icon to replace the default status icon.
style	CSSProperties	Inline styles for the individual toast.
className	string	Custom CSS class for the individual toast.

Styling & Customization

Toastly UI uses CSS variables, making it easy to override styles to match your brand without fighting with specificity.

:root {
  --toastly-font: 'Inter', sans-serif;
  --toastly-z-index: 5000;
}

/* Example: Override the Modern Variant */
.toastly-variant-modern {
  background-color: #fafafa;
  border-radius: 12px;
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

Created with ❤️ by Mehefuj Ali