tw-noti
v1.2.1
Published
[![npm version](https://img.shields.io/npm/v/tw-noti.svg?label=version)](https://www.npmjs.com/package/tw-noti) [![npm downloads](https://img.shields.io/npm/dw/tw-noti.svg)](https://www.npmjs.com/package/tw-noti) [![package license](https://img.shields.io
Downloads
78
Maintainers
Readme
tw-noti
TailwindCSS Toast Notifications and Provider for React Applications
A simple way to set up Toast notifications in your React projects when you are using Tailwind CSS.
Installation
Make sure you have TailwindCSS setup in your project
npm install tw-noti
Usage
- Import the
ToastProvider
and use it to wrap your application:
import { ToastProvider } from 'tw-noti';
export default function App() {
return (
<>
<ToastProvider
maxToasts={3}
timeout={3000}
reverseStackOrder
containerClasses='right-12 bottom-12'
>
<Child />
</ToastProvider>
</>
);
}
- In a child component, import the
useToast
hook and use it to eitherenqueue
ordequeue
your Toast notification:
import { useToast } from 'tw-noti';
const Child = () => {
// Initialize the hook:
const { enqueueToast } = useToast();
const handleClick = () => {
// Pass your message and the type of Toast you would like to display:
enqueueToast({ content: 'This is a notification', type: 'success' });
};
return (
<div class='container' style={{ width: '80 %', margin: '0 auto' }}>
<button
className='text-white bg-blue-700 hover:bg-blue-800 focus:ring-4 focus:ring-blue-300 font-medium rounded-lg text-sm px-5 py-2.5 mr-2 mb-2 dark:bg-blue-600 dark:hover:bg-blue-700 focus:outline-none dark:focus:ring-blue-800'
onClick={handleClick}
>
Show a toast!
</button>
</div>
);
};
export default Child;
Components
ToastProvider
The ToastProvider
houses the ToastContainer
and the Toaster
.maxToasts
| Prop | type | default | description |
| ------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| maxToasts
| number | 3 | Number of toasts that can be displayed at one time |
| reverseStackOrder
| boolean | false | If true
, reverses the order in which Toasts are rendered |
| persist
| boolean | false | If false
, toasts will be dismissed after timeout |
| timeout
| number | 3000 | If persist
set to false
, amount of time (ms) Toasts wait before automatically dismissing |
| buttonClasses
| string | 'h-8 w-8 ml-auto -mx-1.5 -my-1.5 rounded-lg focus:ring-2 focus:ring-gray-300 p-1.5 inline-flex dark:text-gray-500 text-gray-400 dark:hover:text-white hover:text-gray-900 dark:bg-gray-800 bg-white dark:hover:bg-gray-700 hover:bg-gray-100' | Accepts Tailwind classes to override default Toast action button styles |
| containerClasses
| string | 'absolute bottom-12 left-12' | Accepts Tailwind classes to override default Toast container styles |
| iconClasses
| Theme['icon']['classes'] | See Theme | Accepts Tailwind classes to override default Toast icon styles |
| layoutClasses
| string | 'animate-fade-down animate-ease-in-out flex items-center w-full max-w-xs p-4 rounded-lg shadow dark:bg-gray-800 bg-white dark:text-gray-400 text-gray-500' | Accepts Tailwind classes to override default Toast layout styles |
| messageClasses
| string | 'ml-3 text-sm font-normal' | Accepts Tailwind classes to override default Toast message styles |
Hooks
useToast
useToast is a React hook that provides access to the ToastContext and its associated props.
Usage
import { useToast } from './useToast';
const MyComponent = () => {
const toastContext = useToast();
// ...
};
Arguments
None.
Returns
Returns the ToastContextProps associated with the ToastContext.
interface ToastContextProps {
reverseStackOrder: boolean;
theme: Theme;
toasts: Toast[];
enqueueToast: ({ content, type }: { content: string; type: string }) => void;
dequeueToast: (id: number) => void;
}
Errors
If useToast is used outside of a ToastProvider, an error will be thrown.
Default Toast Variants
| Type | Description |
| --------- | --------------------------------------------------------------------------- |
| info
| Blue - Used for general notifications, alerts, and messages |
| success
| Green - Used for success messages |
| error
| Red - Used for errors, access denied messages, and other bad stuff |
| warning
| Orange - Used for warning messages or things the user must pay attention to |
Customization
To override the default styling, you can apply Tailwind CSS classes to the ToastProvider component via its various props.
Examples:
- Position the notifications in the bottom-right corner:
<ToastProvider containerClasses='right-12 bottom-12'>
<Child />
</ToastProvider>
- Change the layout background color and change the text color:
<ToastProvider
layoutClasses='dark:bg-teal-500'
messageClasses='dark:text-black'
>
<Child />
</ToastProvider>
- Customize the close button:
<ToastProvider buttonClasses='dark:bg-white'>
<Child />
</ToastProvider>
- Edit the icon:
<ToastProvider
iconClasses={{
info: { altText: 'Green Icon', classes: 'dark:bg-orange-500' },
error: { altText: 'Teal Icon', classes: 'dark:bg-teal-500' }
}}
>
<Child />
</ToastProvider>
Default Theme
- ButtonClasses:
'h-8 w-8 ml-auto -mx-1.5 -my-1.5 rounded-lg focus:ring-2 focus:ring-gray-300 p-1.5 inline-flex dark:text-gray-500 text-gray-400 dark:hover:text-white hover:text-gray-900 dark:bg-gray-800 bg-white dark:hover:bg-gray-700 hover:bg-gray-100'
- ContainerClasses:
'absolute bottom-12 left-12'
- LayoutClasses:
'animate-fade-down animate-ease-in-out flex items-center w-full max-w-xs p-4 rounded-lg shadow dark:bg-gray-800 bg-white dark:text-gray-400 text-gray-500'
- MessageClasses:
'ml-3 text-sm'
- IconClasses:
{
error: {
altText: 'Big X icon',
classes: 'h-8 w-8 inline-flex items-center justify-center flex-shrink-0 rounded-lg dark:text-red-200 text-red-500 dark:bg-red-800 bg-red-100',
},
info: {
altText: 'Info Circle icon',
classes: 'h-8 w-8 inline-flex items-center justify-center flex-shrink-0 rounded-lg dark:text-blue-200 text-blue-500 dark:bg-blue-800 bg-blue-100',
},
success: {
altText: 'Checkmark icon',
classes: 'h-8 w-8 inline-flex items-center justify-center flex-shrink-0 rounded-lg dark:text-green-200 text-green-500 dark:bg-green-800 bg-green-100',
},
warning: {
altText: 'Warning icon',
classes: 'h-8 w-8 inline-flex items-center justify-center flex-shrink-0 rounded-lg dark:text-orange-200 text-orange-500 dark:bg-orange-800 bg-orange-100',
}
}
Theme
interface Theme {
button: { classes: string };
container: { classes: string };
icon: {
classes: {
[key: string]: {
altText: string,
classes: string
}
}
};
layout: { classes: string };
message: { classes: string };
}
Toaster Component Reference
<ToastContainer containerClasses=''>
{toasts.map((toast) => (
<ToastLayout layoutClasses=''>
<ToastIcon iconClasses='' />
<ToastMessage messageClasses='' />
<ToastActionBtn buttonClasses='' />
</ToastLayout>
))}
</ToastContainer>