React Toast Manager

A library for notifying users about events. It lets you create customizable toasts in four different screen positions, with several animations and additional options for a seamless user experience.

📦 NPM Package:
https://www.npmjs.com/package/@cynzlic/simple-toasts

✨ Features

• 📍 4 screen positions (left / right × top / bottom)
• 🎨 Multiple toast types
• 🎬 In & out animations
• ⏱ Configurable duration
• 🎯 Max 3 toasts per position
• 🧩 Fully typed (TypeScript + Zod)

📦 Installation

npm install @cynzlic/simple-toasts

✨ Quick Start

1. Install package via npm i @cynzlic/simple-toasts

2. Wrap your app with <ToastContainer/>

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import App from './App.tsx'
import {ToastContainer} from '@cynzlic/simple-toasts'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ToastContainer>
          <App />
    </ToastContainer>
  </StrictMode>,
)

3. Use <ToastManager/> in your app

import "./App.css";
import { ToastManager } from "@cynzlic/simple-toasts";

function App() {
  const showToast = () => {
    ToastManager.Instance.setPosition('left', 'top')
    .setType('info')
    .setTitle('I am a title')
    .setDescription('Hey. I am an info notification')
    .setAnimation('pop', 'zoom-out')
    .setDuration(3000)
    .show();
  };

  return (
      <button onClick={showToast}>show a toast</button>
  );
}

export default App;

ToastManager API

A fluent (chainable) API for creating and displaying toast notifications.

Getting the Instance

const toast = ToastManager.Instance;

Returns the singleton instance of the toast manager.

Methods

setTitle(title: string)

Sets the toast title.

Constraints

• Must be a non-empty string
• Maximum 25 characters

toast.setTitle('Success');

setDescription(description: string)

Sets the toast description.

Constraints

• Must be a non-empty string
• Maximum 80 characters

toast.setDescription('Operation completed successfully');

setType(type: ToastType)

Sets the toast type.

Available values

• 'success'
• 'info'
• 'warning'

toast.setType('success');

setPosition(horizontal: PositionHorizontal, vertical: PositionVertical)

Sets the toast position on the screen.

Horizontal

• 'left'
• 'right'

Vertical

• 'top'
• 'bottom'

Valid combinations

• ('left', 'top')
• ('right', 'top')
• ('left', 'bottom')
• ('right', 'bottom')

⚠️ Maximum 3 toasts per position at the same time

toast.setPosition('right', 'bottom');

setAnimation(animationIn: ToastInAnimation, animationOut?: ToastOutAnimation)

Sets the toast animations.

In animations (animationIn)

• 'slide'
• 'pop'
• 'fade-in-rotate'
• 'bounce'
• 'zoom-blur-in'

Out animations (animationOut, optional)

• 'vanish'
• 'rotate-out'
• 'zoom-out'
• 'pop-out'

toast.setAnimation('slide');

toast.setAnimation('pop', 'zoom-out');

setDuration(duration: number)

Sets how long the toast is displayed (in milliseconds).

Rules

• Must be a positive number
• If not set, the toast will not disappear automatically

toast.setDuration(3000);

setBackground(color: string)

Sets a custom background color for the toast.

toast.setBackground('#1e293b');

show()

Creates and displays the toast.

toast.show();

Full Usage Example

ToastManager.Instance
  .setTitle('Success')
  .setDescription('Operation completed successfully')
  .setType('success')
  .setPosition('right', 'bottom')
  .setAnimation('pop', 'zoom-out')
  .setDuration(3000)
  .setBackground('#1e293b')
  .show();

Default Values

If no options are provided, the following defaults are used:

{
  title: 'Info',
  description: 'Description',
  type: 'info',
  position: ['right', 'top'],
  animation: ['slide', 'pop-out'],
  duration: 0
}

Type Definitions

type ToastType = 'success' | 'info' | 'warning';

type PositionHorizontal = 'left' | 'right';
type PositionVertical = 'top' | 'bottom';

type ToastInAnimation =
  | 'slide'
  | 'pop'
  | 'fade-in-rotate'
  | 'bounce'
  | 'zoom-blur-in';

type ToastOutAnimation =
  | 'vanish'
  | 'rotate-out'
  | 'zoom-out'
  | 'pop-out';