yew-notifications

Notifications components library for Yew. It's like react-toastify but for Yew and more simpler (so far 😏).

TL;DR: documentation.

Motivation

I was writing my personal project crypto-helper some time ago. I was forced to write awful code ([1], [2]) to add some notifications functionality to my web app. So, I decided to write this library that allows the easy showing of notifications to users.

Inspired by yew-toastrack.

Core concepts

First of all, simplicity is one of the main purposes. I would like to have a general provider and hook that will spawn notifications. Something like that:

<Provider>
    // inner components
</Provider>

... and spawn notifications in any inner component using one simple hook:

let notifications = use_notifications();                              
notifications.spawn(/* */);

I managed to implement it as I wanted using the yew ContextProvider. Basically, all notifications are saved in this context provider. But we need to add new notifications, remove old ones, and so on. So the simple Vec inside of the context provider is a bad idea. Actually, it holds the UseReducerDispatcher wrapper into the NotificationsManager. This NotificationsManager can spawn new notifications using the inner UseReducerDispatcher and the context will handle them.

The second goal is customization. I don't want to force users to use only built-in notification components. This is a reason why the NotificationsProvider component and use_notifications hook have generic parameters.

For the notifications provider component, we need to specify two generic parameters:

1. Notifications type. This is a struct that described notification data like title, text, lifetime, etc. You can create your own such struct and use it here. It must implement the Notifiable trait.
2. Notification Factory type. The purpose of this type is actual notification component creation. It must implement the NotifiableComponentFactory trait. When the library will try to render the user's notification, it'll use this factory to create notification yew component from the Notification instance.

<NotificationsProvider<Notification, NotificationFactory> component_creator={/* */}>
    // some inner components
</NotificationsProvider<Notification, NotificationFactory>>

For the use_notifications hook, we need to specify only the notification type:

let notifications = use_notification::<Notification>();                                         
notifications.spawn(Notification::new(/* */));

Pay attention: if you specify the different notification types in the provider and hook then the code will compile but fail in the runtime. But you can use different notification types if they provider components do not overlap.

For example, with fully customized notifications, we can achieve the following result:

_{src. demo site.}

How to use it

1. Decide which notification components to use. yew-notifications already has implemented standard notifications but you can write your own. See basic and custom examples for more information.

# Cargo.toml

# if you want to use standard notification components
yew-notifications = { git = "https://github.com/TheBestTvarynka/yew-notifications.git", features = ["standard-notification"] }

# if you decide to write and use custom notification components
yew-notifications = { git = "https://github.com/TheBestTvarynka/yew-notifications.git" }

2. Include yew-notification styles into your project:

<link data-trunk rel="sass" href="https://raw.githubusercontent.com/TheBestTvarynka/yew-notifications/main/static/notifications_provider.scss" />

This one below is needed only when you decide to use components from the yew-notifications:

<link data-trunk rel="sass" href="https://raw.githubusercontent.com/TheBestTvarynka/yew-notifications/main/static/notification.scss" />

Or you can copy scss file into your project and specify the path to it instead of the link. At this point, the scss file is one possible way to import styles.

3. Wrap needed components into NotificationProvider:

// Notification, NotificationFactory  - your notification types.
// They can be imported from this library or written by yourself (see `custom` example).
// component_creator is an instance of the NotificationFactory
<NotificationsProvider<Notification, NotificationFactory> component_creator={/* */}>
    // some inner components
</NotificationsProvider<Notification, NotificationFactory>>

4. Spawn notifications:

use yew_notifications::use_notification;

// Notification - your notification type.
// It can be imported from this library or written by yourself (see `custom` example).
let notifications_manager = use_notification::<Notification>();
notifications_manager.spawn(Notification::new(...));

See the examples directory for the code examples.

Moving forward

At this point, this library has minimal functionality implemented. I plan to improve it continuously according to my needs and goals. If you have any feature requests, then create an issue with the description. It'll be a priority for me.

Back to top