Name	Name	Last commit message	Last commit date
parent directory ..
cypress	cypress
public	public
src	src
CHANGELOG.md	CHANGELOG.md
README.md	README.md
cypress.json	cypress.json
package.json	package.json
tsconfig.build.json	tsconfig.build.json
vite.config.js	vite.config.js

MagicBell Notification Inbox

This package contains a notification inbox for your site powered by MagicBell.

Note

Don't use this package when you're using React. Use @magicbell/magicbell-react or @magicbell/react-headless instead.

Quick Start

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

<div id="notifications-inbox" />

<script type="module">
  import { renderWidget } from '@magicbell/embeddable';

  const targetElement = document.getElementById('notifications-inbox');
  const options = {
    apiKey: MAGICBELL_API_KEY,
    userEmail: CURRENT_USER_EMAIL,
    height: 500,
  };

  renderWidget(targetElement, options);
</script>

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.

Property	Type	Description
`apiKey`	`string`	The API key of your magicbell.io project
`userEmail`	`string`	The email of the user you want to show notifications for
`userExternalId`	`string`	The external ID of the user you want to show notifications for. See the Users documentation for more information.
`userKey`	`string`	The HMAC for the user. It is recommended to enable HMAC authentication but not required
`theme`	`IMagicBellTheme`	An optional object containing custom color values for the widget, see Custom Themes
`defaultIsOpen`	`boolean`	An optional flag to set the default visibility state of the element returned by the children function. It is `false` by default.
`onNewNotification`	`(notification) => void`	An optional function called when a new notification arrives.
`locale`	`string or CustomLocale`	Locale to use in the components.
`serverURL`	`string`	The url to the notifications backend api service currently defaulted to `https://api.magicbell.com`.
`images?`	`Partial<{ emptyInboxUrl: string; }>`	Image to use when the inbox is empty.

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.

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.

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:

Event name	Description
`notifications.new`	A new notification for the authenticated user was created
`notifications.read`	A notification was marked as read
`notifications.read.all`	All notifications were marked as read
`notifications.unread`	A notification was marked as unread
`notifications.seen`	A notification was marked as seen
`notifications.seen.all`	All notifications were marked as seen
`notifications.delete`	A notification was deleted

`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.

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.

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.

// 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.

// 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:

{
  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',
    },
  },
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

embeddable

embeddable

README.md

MagicBell Notification Inbox

Quick Start

The MagicBell Widget

`renderWidget(targetElement, options)`

Events

Available Events

`on(type, handler)`

`off(type, handler)`

Cleanup

`cleanup(widget)`

`cleanupAll()`

Custom Themes

Files

embeddable

Directory actions

More options

Directory actions

More options

Latest commit

History

embeddable

Folders and files

parent directory

README.md

MagicBell Notification Inbox

Quick Start

The MagicBell Widget

renderWidget(targetElement, options)

Events

Available Events

on(type, handler)

off(type, handler)

Cleanup

cleanup(widget)

cleanupAll()

Custom Themes

`renderWidget(targetElement, options)`

`on(type, handler)`

`off(type, handler)`

`cleanup(widget)`

`cleanupAll()`