Overview

The Toast component library provides two components, HeadlessToast and ReuseToast, to display toast notifications in your React applications. Toasts are temporary, non-intrusive messages that appear at the bottom or top of the screen to provide users with feedback or important information.

Installation

ReuseJS Exposes individual components in there own packages and as such you can install Toast by adding following package to your package.json

yarn add @locoworks/reusejs-react-toast
or 
npm install @locoworks/reusejs-react-toast

External Dependencies

One of the key aspect of a toast component is how they enter and exit the UI. For this we usually apply animation to any our toast components. Reusejs Toast provide user with Animation out of the box. We use framer-motion for applying these animation styles.

Thus you need to add framer-motion to your application to use reusejs-toast

yarn add framer-motion
or
npm install framer-motion

Importing

@locoworks/reusejs-react-toast exports two components for the end user, which they can use depending upon their needs. These components are

  • HeadlessToast
  • ReuseToast

To use above components we have to import them as follows

import {HeadlessToast, ReuseToast} from "@locoworks/reusejs-react-toast";

HeadlessToast

The HeadlessToast component is a part of the Toast component library for React applications("@locoworks/reusejs-react-toast"). It is a higher-order component (HOC) that provides closable behavior to a wrapped component, allowing it to be displayed as a toast notification.

As this component is headless it does not have any UI element to display out of the box instead it falls upon the user to create and style a Toast component, which they can than pass to the HeadlessToast component to be displayed as toast.

Input Parameters

The HeadlessToast component accepts the following input parameters:

  • timeout (number, required): The time in milliseconds for which the toast should remain visible before automatically closing.
  • component (React.ReactNode, required): The React component that will be displayed as the content of the toast.

Return Type

The HeadlessToast component it wraps the provided component with closable behavior and returns an enhanced component with toast behavior. Capture this is an async function. Call this function to mount the set component as a toast.

ReuseToast

ReuseToast Component

The ReuseToast component provides a toast notification with customizable properties such as timeout duration, position, appearance, and progress indicator. It wraps the HeadlessToast component, which adds closable behavior to the toast, allowing it to automatically close after a specified timeout.

Props List

The ReuseToast component accepts the following props:

  1. timeout (number, required): The time in milliseconds for which the toast should remain visible before automatically closing.
  2. label (string, required): The text content of the toast.
  3. toastClasses (string, optional): Additional CSS classes to be applied to the toast element.
  4. icon (React.ReactNode, optional): An optional React node to be displayed as an icon within the toast.
  5. showProgress (boolean, optional): A flag to control the display of a progress bar indicating the remaining time for the toast to close. Default is true.
  6. progressClasses (string, optional): Additional CSS classes to be applied to the progress bar element.
  7. position (string, optional): The position of the toast on the screen. Possible values: "top-left", "top-centre", "top-right", "centre-right", "bottom-right", "bottom-centre", "bottom-left", "centre-left". Default is "bottom-centre".
  8. customToastPosition (string, optional): Custom CSS position value for the toast element if you want to override the pre-defined positions.
  9. customAnimation (object, optional): Custom animation configuration for the toast. It contains the following properties: initial, animate, exit, and transition.

Props Table

PropTypeDescription
timeoutnumber (required)The time in milliseconds for which the toast should remain visible before automatically closing.
labelstring (required)The text content of the toast.
toastClassesstring (optional)Additional CSS classes to be applied to the toast element.
iconReact.ReactNode (optional)An optional React node to be displayed as an icon within the toast.
showProgressboolean (optional)A flag to control the display of a progress bar indicating the remaining time for the toast to close. Default is true.
progressClassesstring (optional)Additional CSS classes to be applied to the progress bar element.
positionstring (optional)The position of the toast on the screen. Possible values: "top-left", "top-centre", "top-right", "centre-right", "bottom-right", "bottom-centre", "bottom-left", "centre-left". Default is "bottom-centre".
customToastPositionstring (optional)Custom CSS position value for the toast element if you want to override the pre-defined positions.
customAnimationobject (optional)Custom animation configuration for the toast. It contains the following properties: initial, animate, exit, and transition.

Usage and examples

Following are some example and code samples for toast example made using ReuseToast and HeadlessToast. You can also find the Code fragment to directly use for yourself

Headless Toast Example

import React from "react";
import { HeadlessToast } from "@locoworks/reusejs-react-toast";
import { ReuseButton } from "@locoworks/reusejs-react-button";
import HomeIcon from "../icons/Home";

const HeadlessToastExample = () => {
	const Toast = () => {
		return (
			<div className="absolute top-10 left-1/2 -translate-x-1/2 bg-black text-white px-3 py-2 rounded">
				<label>This is a sample Toast!</label>
			</div>
		);
	};

	const Toast2 = () => {
		return (
			<div className="absolute bottom-10 left-1/2 -translate-x-1/2 bg-black text-white px-3 py-2 rounded flex items-center justify-center ">
				<span>
					<HomeIcon />
				</span>
				<label>This is toast with Icon</label>
			</div>
		);
	};
	const showToast = async () => {
		await HeadlessToast({
			component: <Toast />,
			timeout: 2000,
		});
	};

	const showToast2 = async () => {
		await HeadlessToast({
			component: <Toast2 />,
			timeout: 3000,
		});
	};

	return (
		<div className="flex flex-col items-center gap-x-3 justify-center py-10 mt-10 border rounded bg-gray-50">
			<ReuseButton
				className="bg-blue-500 px-2 py-1 mt-3"
				onClick={() => {
					showToast();
				}}
			>
				Show First Toast
			</ReuseButton>
			<ReuseButton
				className="bg-blue-500 px-2 py-1 mt-3"
				onClick={() => {
					showToast2();
				}}
			>
				Show Second Toast
			</ReuseButton>
		</div>
	);
};

export default HeadlessToastExample;

Toast Positions Example

import React, { useState } from "react";
import { ReuseToast } from "@locoworks/reusejs-react-toast";
import { ReuseButton } from "@locoworks/reusejs-react-button";

type PositionTypes =
	| "top-left"
	| "top-centre"
	| "top-right"
	| "centre-right"
	| "bottom-right"
	| "bottom-centre"
	| "bottom-left"
	| "centre-left";

const ToastPositionExample = () => {
	const showToast = async () => {
		await ReuseToast({
			label: "Sample Toast",
			timeout: 2000,
			position: currentSelected,
		});
	};
	const options = [
		"top-left",
		"top-centre",
		"top-right",
		"centre-left",
		"centre-right",
		"bottom-left",
		"bottom-centre",
		"bottom-right",
	];

	const [currentSelected, setCurrentSelected] =
		useState<PositionTypes>("top-left");

	return (
		<div className="flex flex-col items-center gap-x-3 justify-center py-10 mt-10 border rounded bg-gray-50">
			<div className="grid grid-cols-3 w-full px-4">
				{options.map((opt, index) => {
					return (
						<React.Fragment key={opt}>
							{index === 4 && <div key="Black option for center toast " />}
							<div
								className="flex gap-x-3 h-10 justify-center items-center bg-white rounded border "
								key={opt}
							>
								<label>{opt[0].toUpperCase() + opt.slice(1)}</label>
								<input
									type="radio"
									value={opt}
									name="option"
									checked={currentSelected === opt}
									onChange={(e) => {
										setCurrentSelected(e.target.value as PositionTypes);
									}}
								/>
							</div>
						</React.Fragment>
					);
				})}
			</div>

			<ReuseButton
				className="bg-blue-500 px-2 py-1 mt-3"
				onClick={() => {
					showToast();
				}}
			>
				Show Toast
			</ReuseButton>
		</div>
	);
};

export default ToastPositionExample;

Custom Position Toast

This example shows a custom toast with custom animation for opacity

import React from "react";
import { ReuseToast } from "@locoworks/reusejs-react-toast";
import { ReuseButton } from "@locoworks/reusejs-react-button";

const CustomPositionExample = () => {
	const showToast = async () => {
		await ReuseToast({
			timeout: 2000,
			label: "Sample Toast in Centre",
			customToastPosition: "absolute inset-0 m-auto h-fit w-fit",
			customAnimation: {
				initial: { opacity: 0 },
				animate: { opacity: 1 },
				exit: { opacity: 0 },
				transition: { duration: 0.2 },
			},
		});
	};

	return (
		<div className="flex flex-col items-center gap-x-3 justify-center py-10 mt-10 border rounded bg-gray-50">
			<ReuseButton
				className="bg-blue-500 px-2 py-1 mt-3"
				onClick={() => {
					showToast();
				}}
			>
				Show Toast
			</ReuseButton>
		</div>
	);
};

export default CustomPositionExample;

Toast With Icon

import React from "react";
import { ReuseToast } from "@locoworks/reusejs-react-toast";
import { ReuseButton } from "@locoworks/reusejs-react-button";
import HomeIcon from "../icons/Home";

const ToastPositions = () => {
	const showToast = async () => {
		await ReuseToast({
			label: "This is toast with Home Icon",
			icon: <HomeIcon />,
			timeout: 3000,
			position: "bottom-centre",
		});
	};

	return (
		<div className="flex flex-col items-center gap-x-3 justify-center py-10 mt-10 border rounded bg-gray-50">
			<ReuseButton
				className="bg-blue-500 px-2 py-1 mt-3"
				onClick={() => {
					showToast();
				}}
			>
				Show Toast
			</ReuseButton>
		</div>
	);
};

export default ToastPositions;

Toast with No Progress Indicator

import React from "react";
import { ReuseToast } from "@locoworks/reusejs-react-toast";
import { ReuseButton } from "@locoworks/reusejs-react-button";
import HomeIcon from "../icons/Home";

const ToastWithNoProgress = () => {
	const showToast = async () => {
		await ReuseToast({
			label: "Toast Home",
			icon: <HomeIcon />,
			showProgress: false,
			timeout: 2000,
			position: "bottom-centre",
		});
	};

	return (
		<div className="flex flex-col items-center gap-x-3 justify-center py-10 mt-10 border rounded bg-gray-50">
			<ReuseButton
				className="bg-blue-500 px-2 py-1 mt-3"
				onClick={() => {
					showToast();
				}}
			>
				Show Toast
			</ReuseButton>
		</div>
	);
};

export default ToastWithNoProgress;

Custom Styles Toast Example

// import React, { useEffect, useState } from "react";
import React from "react";
import { ReuseToast } from "@locoworks/reusejs-react-toast";
import { ReuseButton } from "@locoworks/reusejs-react-button";
import Check from "../icons/Check";

const CustomStyledExample = () => {
	const showToast = async () => {
		await ReuseToast({
			timeout: 2000,
			label: "Success",
			icon: <Check />,
			position: "bottom-centre",
			toastClasses: "bg-green-600 text-white font-bold",
			progressClasses: "absolute bottom-0 left-0 bg-white h-1 w-full",
		});
	};

	return (
		<div className="flex flex-col items-center gap-x-3 justify-center py-10 mt-10 border rounded bg-gray-50">
			<ReuseButton
				className="bg-blue-500 px-2 py-1 mt-3"
				onClick={() => {
					showToast();
				}}
			>
				Show Toast
			</ReuseButton>
		</div>
	);
};

export default CustomStyledExample;

Notes

  • The ReuseToast component internally utilizes the HeadlessToast component to handle the toast's closable behavior.
  • The component allows customization of toast appearance, positioning, and progress indicator, making it suitable for various toast notifications.