@magicbell/magicbell-react

MagicBell-React

MagicBell-React is a set of React components to build a notification widget for your site powered by magicbell.io.

• Full TypeScript support
• Supports preact
• Requires React 16.8+
• Compatible with any browser that supports Proxy

Quick Start

npm i @magicbell/magicbell-react
# or
yarn add @magicbell/magicbell-react

import React from 'react';
import MagicBell, { NotificationCenter } from '@magicbell/magicbell-react';

render(
  <MagicBell apiKey={MAGICBELL_API_KEY} userEmail="[e-mail]">
    {() => <NotificationCenter height={300} />}
  </MagicBell>,
  document.body,
);

Table of Contents

• Components

  • Introduction
  • MagicBell
  • NotificationCenter
  • NotificationList
  • ClickableNotification

• Custom Themes

Introduction

This package is built using MobX. The notification store and its items are MobX observables. To use this package you don't need to know anything about MobX. However, if you build a component, make it observe changes to the observable objects we expose. This is as simple as this:

// Before
export default function MyComponent() {}

// After
import { observer } from 'mobx-react-lite';

function MyComponent() {}
export default observer(MyComponent);

The overhead of observer itself is negligible. You can read more about how to observe MobX objects at the official docs of mobx-react.

Once you make your custom component observe changes, it will be updated automatically.

MagicBell

The MagicBell component is the default export of this package and is the root component for building a widget. It initializes a connection to magicbell.io, renders a bell icon with the number of unseen notifications and keeps the widget updated in real time.

These are all the properties accepted by this component.

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
userKey	string	The HMAC for the user. It is recommended to enable HMAC authentication but not required
children	({ notifications, toggleNotificationCenter }) => JSX.Element	The children function to render all notifications for the user
theme	IMagicBellTheme	An optional object containing custom color values for the widget, see Custom Themes
BellIcon	JSX.Element	An optional react element to be displayed instead of the default bell icon

Children function

This component expects a children function. This is how you render whatever you want to based on the state of the MagicBell.

You can use the notification center from this package (see NotificationCenter):

import React from 'react';
import MagicBell, { NotificationCenter } from '@magicbell/magicbell-react';

render(
  <MagicBell apiKey={MAGICBELL_API_KEY} userEmail="[e-mail]">
    {() => <NotificationCenter height={300} />}
  </MagicBell>,
  document.body,
);

or use one of your own:

import React from 'react';
import MagicBell from '@magicbell/magicbell-react';

render(
  <MagicBell apiKey={MAGICBELL_API_KEY} userEmail="[e-mail]">
    {({ notifications, toggleNotificationCenter }) => (
      <MyOwnNotificationCenter notifications={notifications} />
    )}
  </MagicBell>,
  document.body,
);

The MagicBell component does not render the component returned by the children function by default, only the bell is rendered. When the bell is clicked, the child component is toggled. As shown above, the children function gets the notifications store and a function to manually toggle the notification center. You can access the notifications store through MagicBellContext, too.

NotificationCenter

The NotificationCenter component renders a header, a footer and an infinite scroll list of notifications.

These are all the properties accepted by this component.

Property	Type	Description
height	number	Height in pixels of the infinite scroll list
onAllRead	() => void	An optional callback function called when the "Mark All Read" button is clicked
onNotificationClick	(notification) => void	An optional callback function called when a notification is clicked

NotificationList

The NotificationList component renders an infinite scroll list of notifications. When the user scrolls to the bottom the next page of notifications are fetched and appended to the current array of notifications. By default it renders a ClickableNotification component for each item in the notifications store.

These are all the properties accepted by this component.

Property	Type	Description
height	number	Height in pixels of the infinite scroll list
onItemClick	(notification) => void	An optional callback function called when a notification is clicked
ListItem	({ notification, onItemClick }) => JSX.Element	An optional custom component to use for each item in the list

If the height property is not provided, then the window scroll will be used.

Example: notification center with a custom list item.

ClickableNotification

This component renders the title and content of a notification.

IMPORTANT: When a notification is clicked, the notification is marked as read. If you implement your own component, you might also want to mark the notification as read manually. E.g.:

import React from 'react';
import { observer } from 'mobx-react';

function CustomNotification({ notification, onClick }) {
  const handleClick = () => {
    notification.markAsRead();
    onClick(notification);
  };

  return <div onClick={handleClick}>{notification.title}</div>;
}

export default observer(CustomNotification);

Custom Themes

Is is possible to change the default colors of some elements by providing to the MagicBell component a theme property.

This is the definition of the default theme:

{
  icon: {
    borderColor: '#335EEA',
  },
  header: {
    backgroundColor: '#335EEA',
    textColor: 'white',
  },
  footer: {
    backgroundColor: '#335EEA',
    textColor: 'white',
  },
  unseenBadge: {
    backgroundColor: '#DF4759',
    textColor: 'white',
  },
  notification: {
    default: {
      backgroundColor: 'white',
      textColor: '#2F323C',
      title: {
        textColor: '#161B2D',
      },
    },
    unread: {
      backgroundColor: '#D9E2EF',
      textColor: '#2F323C',
      title: {
        textColor: '#161B2D',
      },
    },
  },
}

You can override any attribute of this theme. Colors can be expressed in HEX or RGB(A).

import React from 'react';
import MagicBell, { NotificationCenter } from '@magicbell/magicbell-react';

const customTheme = {
  icon: {
    borderColor: 'rgba(160, 30, 120, 0.5)',
  },
  header: {
    textColor: 'black',
  },
};

render(
  <MagicBell apiKey={MAGICBELL_API_KEY} userEmail="[e-mail]" theme={customTheme}>
    {() => <NotificationCenter height="300" />}
  </MagicBell>,
  document.body,
);