seturon-toast-notifications
v1.0.6
Published
A configurable, composable, toast notification system for react.
Downloads
42
Maintainers
Readme
Seturon Toast Notifications
A configurable, composable, toast notification system for react.
Install
yarn add seturon-toast-notifications
Use
Wrap your app in the ToastProvider
, which provides context for the Toast
descendants.
import { ToastProvider, useToasts } from 'seturon-toast-notifications';
const FormWithToasts = () => {
const { addToast } = useToasts();
const onSubmit = async value => {
const { error } = await dataPersistenceLayer(value);
if (error) {
addToast(error.message, { appearance: 'error' });
} else {
addToast('Saved Successfully', { appearance: 'success' });
}
};
return <form onSubmit={onSubmit}>...</form>;
};
const App = () => (
<ToastProvider>
<FormWithToasts />
</ToastProvider>
);
ToastProvider Props
For brevity:
PlacementType
is equal to'bottom-left' | 'bottom-center' | 'bottom-right' | 'top-left' | 'top-center' | 'top-right'
.TransitionState
is equal to'entering' | 'entered' | 'exiting' | 'exited'
.
| Property | Description |
| -------------------------------------- | ------------------------------------------------------------------------------------------ |
| autoDismissTimeout number
| Default 5000
. The time until a toast will be dismissed automatically, in milliseconds. |
| autoDismiss boolean
| Default: false
. Whether or not to dismiss the toast automatically after a timeout. |
| children Node
| Required. Your app content. |
| components { ToastContainer, Toast }
| Replace the underlying components. |
| placement PlacementType
| Default top-right
. Where, in relation to the viewport, to place the toasts. |
| portalTargetSelector string
| Which element to attach the container's portal to. Uses document.body
when not provided. |
| transitionDuration number
| Default 220
. The duration of the CSS transition on the Toast
component. |
Toast Props
| Property | Description |
| ---------------------------------- | --------------------------------------------------------------------- |
| appearance | Required. One of success
, error
, warning
, info
|
| children | Required. The content of the toast notification. |
| autoDismiss boolean
| Inherited from ToastProvider
if not provided. |
| autoDismissTimeout number
| Inherited from ToastProvider
. |
| onDismiss: Id => void
| Passed in dynamically. Can be called in a custom toast to dismiss it. |
| placement PlacementType
| Inherited from ToastProvider
. |
| transitionDuration number
| Inherited from ToastProvider
. |
| transitionState: TransitionState
| Passed in dynamically. |
Hook
The useToast
hook has the following signature:
const {
addToast,
removeToast,
removeAllToasts,
updateToast,
toastStack,
} = useToasts();
The addToast
method has three arguments:
- The first is the content of the toast, which can be any renderable
Node
. - The second is the
Options
object, which can take any shape you like.Options.appearance
is required when using theDefaultToast
. When departing from the default shape, you must provide an alternative, compliantToast
component. - The third is an optional callback, which is passed the added toast
ID
.
The removeToast
method has two arguments:
- The first is the
ID
of the toast to remove. - The second is an optional callback.
The removeAllToasts
method has no arguments.
The updateToast
method has three arguments:
- The first is the
ID
of the toast to update. - The second is the
Options
object, which differs slightly from the add method because it accepts acontent
property. - The third is an optional callback, which is passed the updated toast
ID
.
The toastStack
is an array of objects representing the current toasts, e.g.
[
{
content: 'Something went wrong',
id: 'generated-string',
appearance: 'error',
},
{ content: 'Item saved', id: 'generated-string', appearance: 'success' },
];
Replaceable Components
To bring each toast notification inline with your app, you can provide alternative components to the ToastProvider
:
import { ToastProvider } from 'seturon-toast-notifications';
const MyCustomToast = ({ appearance, children }) => (
<div style={{ background: appearance === 'error' ? 'red' : 'green' }}>
{children}
</div>
);
const App = () => (
<ToastProvider components={{ Toast: MyCustomToast }}>...</ToastProvider>
);
To customize the existing component instead of creating a new one, you may import DefaultToast
:
import { DefaultToast } from 'seturon-toast-notifications';
export const MyCustomToast = ({ children, ...props }) => (
<DefaultToast {...props}>
<SomethingSpecial>{children}</SomethingSpecial>
</DefaultToast>
);