Screen notifications

The foundation-notifications package enables you to create and display a range of different screen notifications in the client application, including:

• alert
• toast
• banner
• snackbar
• dialog.

These notifications are configurable and can be used in different scenarios, ranging from status update to interactive user alerts.

Your application must use the notification-listener component to manage all your notifications. This ensures a consistent user experience.

For detailed information on the API and configurations, see the API documentation.

A complete example

Here is an example that shows a dialog notification component. You can click on the button, see the dialog and click to remove it. The complete code is shown below, including:

• the custom element for the button to trigger the event
• the configuration of the dialog with its title, message and the label that enables you to remove the dialog

Show Dialog

Genesis

 import { showNotificationDialog } from '@genesislcap/foundation-notifications';

 @customElement({
   name: 'my-element',
   template: html`
     <div class="container">
       <rapid-button @click=${(x) => x.showDialog()}>Show Dialog</rapid-button>
     </div>
   `,
 })
 export class MyElement extends GenesisElement {
   showDialog() {
     showNotificationDialog(
       {
         title: 'Important message',
         body: 'Lorem ipsum',
         dialog: {
           confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
           dismissingAction: {
             label: 'Dismiss',
             action: () => console.log('Lorem ipsum'),
           },
         },
       },
       'rapid',
     );
   }
 }

React

import { showNotificationDialog } from '@genesislcap/foundation-notifications';

export function MyComponent() {
  const showDialog = (event) => {
    showNotificationDialog(
      {
        title: 'Important message',
        body: 'Lorem ipsum',
        dialog: {
          confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
          dismissingAction: {
            label: 'Dismiss',
            action: () => console.log('Lorem ipsum'),
          },
        },
      },
      'rapid',
    );
  };

  return (
    <rapid-button onClick={showDialog}>Show Dialog</rapid-button>
  );
}

Angular

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { showNotificationDialog } from '@genesislcap/foundation-notifications';

@Component({
  selector: 'my-root',
  template: `
    <rapid-button
      (click)="showDialog($event)"
    >Show Dialog</rapid-button>
  `,
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  imports: [FormsModule],
})
export class AppComponent {
  showDialog(event: Event) {
    showNotificationDialog(
      {
        title: 'Important message',
        body: 'Lorem ipsum',
        dialog: {
          confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
          dismissingAction: {
            label: 'Dismiss',
            action: () => console.log('Lorem ipsum'),
          },
        },
      },
      'rapid',
    );
  }
}

info

The complete example above shows you how to create a notification in the context of the component library you're using.

In the Notification examples section below, there is a simple example for each component; each example only shows the function that creates the notification, but you can use that in any of the component libraries, as shown in the complete example.

Notification components

These are the notification components you can use:

• Alert: This is a quick messages that shares important information without interrupting the user.
• Toast: This is a short, auto-closing notification that is displayed at the edge of screen. Toasts are ideal for transient messages, such as success confirmations or error notifications.
• Banner: This shows important notifications, such as messages for system updates. It appears at the top of screen.
• Snackbar: This is an interactive notification that appears at the bottom of the screen. Each snackbar persists until dismissed.
• Dialog: This is used for displaying critical notifications; a dialog blocks the underlying interface until it has been dismissed by user action. You can use this to display a confirmation dialog when deleting a user, for example.

Notification examples

The notifications components implemented by the foundation-notifications package are designed to serve specific use cases. These components aid users by providing timely feedback, warning or interactive prompts.

The example for each component simply shows the function that creates that notification. For the broader context, make sure you have looked at the complete example.

Alert

Alerts are simple, non-intrusive notifications that are used for giving information to the user without interrupting their workflow. Alerts are great for showing messages that don't require user interaction, such as updates, confirmations or warnings. An alert functions similarly to the built-in JavaScript alert() method.

Here is an example of using the showNotificationAlert method to show an alert. You can click on the Show Alert button to view the alert message.

For the parameters, refer to AlertStructure in the package API documentation.

Show Alert

 showNotificationAlert({ title: 'Important message', body: 'Lorem ipsum' });

Toast

Toast notifications are short, auto-closing notifications that are displayed at the edge of the screen. They are used for transient messages, such as success confirmations, error notifications or updates that don't require user acknowledgement.

Here is an example of using the showNotificationToast method to show a toast. You can click on the Show Toast button to view the toast message, which slides in from the top right. You can click to remove it, or you can leave it and it will disappear after a few seconds.

For the parameters, refer to ToastStructure in the package API documentation.

Show Toast

 showNotificationToast(
   {
   title: 'Important message',
   body: 'Lorem ipsum',
   toast: {
     autoClose: true,
     closeTimeout: 3000,
     type: 'success',
   },
 },
 'rapid',
 );

As mentioned before, toast notifications automatically close after a specified duration, using the autoClose and closeTimeout options. Like snackbar, they can be styled using the type option that supports error, success, warning and info styles.

Banner

Banner notifications are used for delivering key messages. They appear at the top of the screen. A banner usually includes confirming and dismissing actions with callbacks.

Here is an example of using the showNotificationBanner method to display a banner. You can click on the Show Banner button to view the banner message. This scrolls to the top of the page before displaying the banner, which you can remove using either the Confirm or Dismiss link. (Then you'll have to scroll back here.)

For the parameters, refer to BannerStructure in the package API documentation.

Show Banner

 showNotificationBanner(
   {
     body: 'Lorem ipsum',
     banner: {
       confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
       dismissingAction: {
         label: 'Dismiss',
         action: () => console.log('Lorem ipsum'),
       },
     },
   },
   'rapid',
 );

Snackbar

A snackbar is a notification that appears at the bottom of the screen. These notifications can have interactive buttons, unlike toasts. They can be used for brief updates that require user interaction, such as showing a status message or confirming an action.

When you configure a snackbar, use the type property to set the notification style. Supported types are:

• error
• success
• info
• warning

Here is an example of using the showNotificationSnackbar method to display a snackbar. You can click on the Show Snackbar button to view the snackbar at the bottom left of the screen. You can click on the Confirm link to remove it.

For the parameters, refer to SnackbarStructure in the package API documentation.

Show Snackbar

 showNotificationSnackbar(
 {
   body: 'Lorem ipsum',
   snackbar: {
     confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
     type: 'error',
   },
 },
 'rapid',
);

snackbar is persistent until dismissed. If you want a snackbar to disappear automatically after a short time, set the autoClose property in the snackbar config.

  showNotificationSnackbar(
    {
      body: 'Lorem ipsum',
      snackbar: {
        confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
        type: 'error',
        autoClose: true
      },
    },
    'rapid',
  );

Dialog

The dialog notification component uses a modal-like window to display notification. These notifications require the user to take an action before proceeding; they block the underlying interface until dismissed. Therefore, these are used for critical interactions such as warnings, confirmations or important announcements. This component also supports multiple action buttons.

One of the most common use cases for dialog is to force the user to confirm before deleting.

To show multiple action buttons in a dialog, use the confirmingActions property.

Here is an example of using the showNotificationSnackbar method to display a dialog:

showNotificationDialog(
  {
    title: 'Important message',
    body: 'Lorem ipsum',
    dialog: {
      confirmingActions: [
        { label: 'Confirm', action: () => console.log('Lorem ipsum') },
        { label: 'Save', action: () => console.log('Lorem ipsum') }
      ],
      dismissingAction: {
        label: 'Dismiss',
        action: () => console.log('Lorem ipsum'),
      },
    },
  },
  'rapid',
);

The notification-listener component

Your client app must have a notification-listener at the top of the component tree. Any child under this notification-listener component can dispatch a custom NotificationEvent event.

The rapid-notification-listener component listens for notification events dispatched from any part of your application. It processes the event payload and dynamically displays the appropriate notification component (e.g. alert or toast).

This centralizes notification management and makes it easy to handle different types of notification in a consistent and modular way.

Using the notification listener

The easiest way to see how to set up and use the Notification listener is to follow an example. These are the steps:

1. Wrap your application with the notification-listener

You must place the notification-listener component at the top of the component tree to ensure it can capture events from any child component. You can find the rapid-design-system-provider tag in your application and place the notification-listener tag inside it, whether you're using React, Angular, or Genesis framework.

<rapid-design-system-provider>
  <rapid-notification-listener>
    // other application components go here
  </rapid-notification-listener>
</rapid-design-system-provider>

2. Dispatch the notification using NOTIFICATION_EVENT

To dispatch the notification, use NotificationEvent.NOTIFICATION_EVENT. You can specify the type of notification component you want to display in the config object. For this example, we are displaying a snackbar.

this.$emit( NotificationEvent.NOTIFICATION_EVENT,
  {
    title: 'Important message',
    body: 'Lorem ipsum',
    config: {
      snackbar: {
        confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
        type: 'error',
        autoClose: true
      },
    },
  } as NotificationStructure,)

3. Provide a UI element to trigger the notification

Now you need to provide a UI element that can trigger a notification. The code below creates a button that can trigger the notification event from a child component.

Genesis

import {NotificationEvent, NotificationStructure} from '@genesislcap/foundation-notifications'
...
@customElement({
  name: 'my-element',
  template: html`
    <div class="container">
      <rapid-button @click=${(x) => x.triggerNotification()}>Show Notification</rapid-button>
    </div>
  `,
})
export class MyElement extends GenesisElement {
  triggerNotification() {
    this.$emit( NotificationEvent.NOTIFICATION_EVENT,
      {
        title: 'Important message',
        body: 'Lorem ipsum',
        config: {
          snackbar: {
            confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
            type: 'error',
            autoClose: true
          },
        },
      } as NotificationStructure,)
  }
}

React

import { NotificationEvent, NotificationStructure } from '@genesislcap/foundation-notifications';
import { useRef } from 'react';

export function MyComponent() {
  const ref = useRef();
  const triggerNotification = (event) => {
    const notificationPayload = {
      title: 'Important message',
      body: 'Lorem ipsum',
      config: {
        snackbar: {
          confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
          type: 'error',
          autoClose: true
        },
      },
    } as NotificationStructure;
    ref.current.dispatchEvent(customEventFactory(NotificationEvent.NOTIFICATION_EVENT, notificationPayload))
  };

  return (
    <rapid-button onClick={triggerNotification} ref={ref}>Show Notification</rapid-button>
  );
}

customEventFactory is a helper function to create events in the expected payload format. You can either import it from the PBC module if you're using it, or copy this function into your codebase.

export function customEventFactory(type: string, detail?: any) {
    return new CustomEvent(type, {
        bubbles: true,
        cancelable: true,
        composed: true,
        detail,
    });
}

Angular

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { NotificationEvent, NotificationStructure } from '@genesislcap/foundation-notifications';

@Component({
  selector: 'my-root',
  template: `
    <rapid-button
      (click)="triggerNotification($event)"
    >Show Notification</rapid-button>
  `,
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  imports: [FormsModule],
})
export class AppComponent {
  constructor(private el: ElementRef) {}
  triggerNotification(event: Event) {
    const notificationPayload = {
      title: 'Important message',
      body: 'Lorem ipsum',
      config: {
        snackbar: {
          confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
          type: 'error',
          autoClose: true
        },
      },
    } as NotificationStructure;
    this.el.nativeElement.dispatchEvent(customEventFactory(NotificationEvent.NOTIFICATION_EVENT, notificationPayload));
  }
}

customEventFactory is a helper function to create events in the expected payload format. You can either import it from the PBC module if you're using it, or copy this function into your codebase.

export function customEventFactory(type: string, detail?: any) {
    return new CustomEvent(type, {
        bubbles: true,
        cancelable: true,
        composed: true,
        detail,
    });
}

Additionally, you can provide the resource-name attribute to the notification-listener component. This attribute enables the component to connect to a datasource and listen to the notifications on actions such as insert, update or delete performed on the specified resource-name.

Installation

To enable this module in your application:

1. Add @genesislcap/foundation-notifications as a dependency in your package.json file.

{
  "dependencies": {
    "@genesislcap/foundation-notifications": "latest"
  },
}

2. Run the $ npm run bootstrap command. (Whenever you change the dependencies of your project, you should always run this command to rebuild.) You can find more information in the package.json basics page.