@boxfish-studio/react-notification-manager

Installation 🧰

$ npm i @boxfish-studio/react-notification-manager

or yarn

$ yarn add @boxfish-studio/react-notification-manager

How to use 📝

• Wrap your app in the NotificationProvider:

import { NotificationProvider } from '@boxfish-studio/react-notification-manager'
<NotificationProvider>
    <App />
</NotificationProvider>

• Import the NotificationManager and place it in your layout:

import { NotificationManager } from '@boxfish-studio/react-notification-manager'

const Layout = () => {
    return (
        <div>
            // ...
            <NotificationManager />
        </div>
    )
}

• Use the useNotification hook:

import { useNotification, type NotificationType } from '@boxfish-studio/react-notification-manager'

const Button = () => {
    const { showNotification } = useNotification()

    const addNotification = () => {
        showNotification({
            message: "I'm a toast!",
            type: NotificationType.Info,
            duration: 5000, // Optional
        })
    }

    return <button onClick={addNotification}>Click on me to show a notification!</button>
}

Customization 🖌️

The NotificationManager component accepts a configuration prop to allow you to customize your notifications. Custom configuration must be of type INotificationConfiguration. All available props are shown below:

interface INotificationConfiguration {
    hasIcon?: boolean
    icons?: {
        [key in NotificationType]?: string
    }
}

enum NotificationType {
    Success = 'success',
    Error = 'error',
    Warning = 'warning',
    Info = 'info',
}

NotificationManager Props

Name	Description
hasIcon	If the Notification should contain an icon
icons	An object with the notification type as key, and an image url as a value.

Example:

import { NotificationManager, type INotificationConfiguration } from '@boxfish-studio/react-notification-manager'

const Layout = () => {
    // Optional configuration
    const configuration: INotificationConfiguration = {
        hasIcon: true,
        icons: {
            warning: '/custom-warning-icon.svg',
        },
    }

    return (
        // ...
        <NotificationManager configuration={configuration} />
    )
}

Styling

All the elements of the components contain classes that you can point to in your styles to customize the appearance of the notifications, just override the styles in your global css file.

Example:

.notification-manager {
    bottom: 2rem;
    left: 2rem;
    /* To remove the default right position */
    right: unset;

    .notification__toast {
        border-radius: 8px;
    }

    .notification--warning {
        background-color: #f58223;
    }

    .notification__message {
        color: black;
        font-size: 18px;
        font-weight: 500;
    }

}

Utility functions

The useNotification hook returns three functions:

const { showNotification, removeNotification, updateNotification } = useNotification()

• showNotification: Adds a notification. Receives an object with the notification properties.

showNotification({
    message: "I'm a toast!",
    type: NotificationType.Info,
    duration: 5000, // Optional
})

Name	type	Description	Required
message	string	The message that will show up in the notification.	true
type	NotificationType	The type of the notification. This will change then icon and classes in the notification.	true
duration	number	Duration in milliseconds that will last the toast until the user closes it. Use 0 to make it infinite.

• removeNotification: Removes a notification. Receives an id of the notification to remove.

removeNotification(id)

• updateNotification: Updates a notification. Receives an id of the notification to update, and an object with the notification properties to update.

updateNotification(id, {
    message: 'ERROR!',
    type: NotificationType.Error,
    duration: 0, // Doesn't close automatically.
})

Notifications

The useNotification hook also returns an array with all the notifications. This array is of type INotification[]. You can use this array to manage your notifications whenever you want.

const { notifications } = useNotification()

interface INotification {
    id: string
    message: string
    type: NotificationType
    duration?: number
}

Made with :heart: by [Boxfish Studio](https://boxfish.studio/).