@open-pioneer/notifier

This package allows a developer to emit global notifications from any application component and provides a component to display the notifications.

Usage

Displaying notifications in an application

The <Notifier /> must be used in your app's UI , otherwise notifications from application components are not shown. It should be present exactly once.

import { Notifier } from "@open-pioneer/notifier";

export function AppUI() {
    return (
        <>
            <Notifier />
            {/* The rest of your application */}
        </>
    );
}
Copy

Note: In most cases the notifier should be located at or near the root of your app's UI.

The implementation of <Notifier /> is based on Chakra's Toast.

Configuring the notifier

The notifier can be configured by specifying the following package properties:

export interface NotifierProperties {
    /**
     * The position for new notifications.
     *
     * @default "top-right"
     */
    position?: "top" | "top-left" | "top-right" | "bottom" | "bottom-left" | "bottom-right";
}
Copy

For example, to show notifications in the top-left corner of your application:

// app.ts
const Element = createCustomElement({
    // ...
    config: {
        properties: {
            "@open-pioneer/notifier": {
                position: "top-left"
            } satisfies NotifierProperties
        }
    }
    // or use resolveConfig()
});
Copy

Emitting notifications

Reference the interface name notifier.NotificationService to inject an instance of NotificationService. That service can be used to emit events from any service or UI component in the application:

const notificationService = ...; // injected
notificationService.notify({
    level: "info",
    title: "Job complete",
    message: "Optional additional message ..."
})
Copy

All options in notify are optional, but at least the title or message should be specified.

The following options are supported by the service:

export type NotificationLevel = "success" | "info" | "warning" | "error";

export interface NotificationOptions {
    /** The title of the notification. */
    title?: string | ReactNode | undefined;

    /** An optional message, shown below the title. */
    message?: string | ReactNode | undefined;

    /**
     * The level of this notification.
     * @default "info"
     */
    level?: NotificationLevel | undefined;

    /**
     * The duration (in milliseconds) how long the notification is displayed.
     * By default, notifications are displayed until they are explicitly closed by the user.
     *
     * Note that important messages should not be hidden automatically for a11y reasons.
     */
    displayDuration?: number | undefined;
}
Copy

Closing all notifications

All currently displayed notifications can be closed by calling the closeAll method on the NotificationService:

const notificationService = ...; // injected
notificationService.closeAll();
Copy

License

Apache-2.0 (see LICENSE file)