MagicBell Embeddable Widget

This package contains a notification inbox for your site powered by MagicBell. Please prefer the React or React Headless packages if you're using React.

Quick Start

shell
npm i @magicbell/embeddable
# or
yarn add @magicbell/embeddable

html

The MagicBell Widget

The renderWidget function creates and palaces a MagicBell widget on your web page.

renderWidget(targetElement, options)

• targetElement HTMLElement

The MagicBell widget is rendered within the provided targetElement.

• options WidgetProps

Options to configure the MagicBell widget.

• returns MagicBellEventEmitter

An event emitter which enables you to listen to and act upon MagicBell events.

NOTE: For multiple calls to the renderWidget, the same emitter instances is returned.

javascript
import { renderWidget } from '@magicbell/embeddable';

const targetElement = document.getElementById('magicBellTargetElement');
const emitter = renderWidget(targetElement, options);

Events

An event emitter is returned by renderWidget which enables you to listen to and act upon MagicBell events. For example, you may want to play a sound for new notifications or synchronize your UI with the read state of a notification in the inbox.

Note: The underlying emitter library used is mitt. Only the on and off methods are exposed.

javascript
import { renderWidget } from '@magicbell/embeddable';

const emitter = renderWidget(targetElement, options);

emitter.on('notifications.new', (event) => {
  console.log('new notification received', event);
});

Available Events

This is a list of events you can listen to:

on(type, handler)

This method is used to subscribe to events of a certain type. The provided handler is a function that will be called every time the event occurs. See mitt on for more details.

• type String

The name of one of the events as listed in the table above.

• handler (event: { data, source }) => void

The handler to run when the event occurs. The handler receives a single object argument. This event object, has two properties: data and source.

• event.data is an object containing notification data related to the event. For example the notification object that was read in case of notifications.read.

• event.source is either local or remote. Local events imply that the user did something to cause the event to be triggered. Fore example, manually marking a notification as read. Remote events are caused by a remote change. Either MagicBell pushed a change, like a new notification, or the user did something on another client or browser tab.

javascript
import { renderWidget } from '@magicbell/embeddable';

const widget = renderWidget(targetElement, options);

function onRead({ data, source }) {
  console.log('notification source', source);
  console.log('notification read', data);
}

widget.on('notifications.read', onRead);

off(type, handler)

This is the method to call if you need to stop listening to events that you're subscribed to. See mitt off for more details.

• type String

The name of one of the event that you're currently subscribed to. Passing * will detach all handlers.

• handler (event: { data, source }) => void

The currently attached handler, that you wish to detach. Required because multiple handlers can be attached to the same notification type.

javascript
import { renderWidget } from '@magicbell/embeddable';

const emitter = renderWidget(targetElement, options);

function onRead({ data }) {
  console.log('notification read', data);
}

function onRead2({ data }) {
  console.log('notification read2', data);
}

// Assign more than one function to an emitter action
widget.on('notifications.read', onRead);
widget.on('notifications.read', onRead2);

// Turn off the onRead function
emitter.off('notifications.read', onRead);

Cleanup

In some frameworks, such as Vue.js and Angular, you will need to manually clean up any MagicBell widgets created with renderWidget.

These methods assure that any MagicBell widget is cleaned up.

cleanup(widget)

This is the method to call if you want to explicitly unmount a MagicBell widget.

• widget HTMLElement

The element containing the magicbell widget.

javascript
// Single widget cleanup
import { renderWidget, cleanup } from '@magicbell/embeddable';

const emitter = renderWidget(targetElement, options);
cleanup(targetElement); // immediately cleanup and unmount the widget

cleanupAll()

This is the method to call if you want to explicitly unmount all MagicBell widgets.

javascript
// Multiple widget cleanup
import { renderWidget, cleanup } from '@magicbell/embeddable';

const emitter = renderWidget(targetElement, options);
renderWidget(targetElement, options);
cleanupAll(); // unmount all widgets

Custom Themes

Is is possible to customize the text color, font size and border radius of some elements by providing to the MagicBell component a theme property. This is going to be deep merged with the default theme.

This is the definition of the default theme:

javascript
{
  icon: {
    borderColor: '#3498F4',
    width: '24px',
  },
  header: {
    backgroundColor: '#3498F4',
    backgroundOpacity: 1,
    borderRadius: '8px',
    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif',
    fontSize: '14px',
    textColor: 'white',
    textAlign: 'left',
    textTransform: 'none',
  },
  footer: {
    backgroundColor: '#3498F4',
    backgroundOpacity: 1,
    borderRadius: '8px',
    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif',
    fontSize: '14px',
    textColor: 'white',
    textAlign: 'right',
    textTransform: 'none',
  },
  unseenBadge: {
    backgroundColor: '#DF4759',
    backgroundOpacity: 1,
    borderRadius: '2px',
    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif',
    fontSize: '14px',
    textColor: 'white',
    textAlign: 'left',
    textTransform: 'none',
  },
  container: {
    backgroundColor: '#FFFFFF',
    backgroundOpacity: 1,
    borderRadius: '8px',
    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif',
    fontSize: '14px',
    textAlign: 'left',
    textColor: '#3A424D',
    textTransform: 'none',
  },
  notification: {
    default: {
      backgroundColor: '#3498F4',
      backgroundOpacity: 0.1,
      borderRadius: '8px',
      fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif',
      fontSize: '14px',
      textColor: '#3A424D',
      textAlign: 'left',
      textTransform: 'none',
    },
    unread: {
      backgroundColor: '#D9E2EF',
      backgroundOpacity: 0.1,
      borderRadius: '8px',
      fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif',
      fontSize: '14px',
      textColor: '#3A424D',
      textAlign: 'left',
      textTransform: 'none',
    },
    unseen: {
      backgroundColor: '#D9E2EF',
      backgroundOpacity: 0.05,
      borderRadius: '8px',
      fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif',
      fontSize: '14px',
      textColor: '#3A424D',
      textAlign: 'left',
      textTransform: 'none',
    },
  },
}