@magicbell/react

React SDK

This package contains the React components to build a notifications UI for your site powered by MagicBell.

Quick Start

npm install @magicbell/react

Authentication

You'll need a User JWT to use the SDK. You can generate these on your own server. Read our Authentication Docs to learn how to do this.

ContextProvider

Provides the MagicBell context to all components in the SDK.

Wrap your app in this component to enable access to the MagicBell API client, local-first user/session state, and shared configuration. Required for components like Inbox, FloatingInbox, and SlackButton to function.

import * as React from "react";
import Provider from "@magicbell/react/context-provider";
import FloatingInbox from "@magicbell/react/floating-inbox";

function App(props: any) {
  return (
    <Provider token="${USER_JWT}">
      <nav>
        <div>logo</div>
        <FloatingInbox />
      </nav>
      <main>your content here</main>
    </Provider>
  );
}

export default App;

Properties

Name	Type	Default	Description
token *	string		The MagicBell User JWT
persist	boolean	true	Persist data locally so it remains on page reload
children	Element		Elements to render inside the provider.

FloatingInbox

A floating version of the notification inbox, toggled by a button.

Renders the inbox inside a floating panel positioned relative to a trigger. Ideal for embedding in navigation bars or headers. Supports full customization of placement, dimensions, trigger, and inbox content.

import * as React from "react";
import Provider from "@magicbell/react/context-provider";
import FloatingInbox from "@magicbell/react/floating-inbox";

function App(props: any) {
  return (
    <Provider token="${USER_JWT}">
      <FloatingInbox
        placement="bottom-start"
        height={500}
        width={400}
        offset={10}
      />
    </Provider>
  );
}

export default App;

Properties

Name	Type	Default	Description
defaultOpen	boolean	false	Whether the inbox should be open by default.
height	number	400	The height of the floating inbox panel in pixels.
offset	OffsetOptions	8	Offset of the inbox from the trigger button, in pixels. Can be a single number or an object with main/cross axis.
placement	Placement	bottom-start	Where to place the inbox relative to the trigger button. E.g. 'bottom-end', 'top-start', etc.
width	number	400	The width of the floating inbox panel in pixels.
ButtonComponent	Component	InboxButton	The component used to trigger the inbox, typically a bell icon. It will receive onClick and ref props.
InboxComponent	Component	Inbox	The inbox component to render inside the floating panel. Defaults to <Inbox /> if not provided.

Inbox

A notification inbox component that displays a list of notifications for the current user.

Supports pagination, read/unread states, and customizable rendering of notification items. Can be embedded directly in a page or used in combination with floating UIs using FloatingInbox.

import * as React from "react";
import Provider from "@magicbell/react/context-provider";
import Inbox from "@magicbell/react/inbox";

function App(props: any) {
  return (
    <Provider token="${USER_JWT}">
      <Inbox />
    </Provider>
  );
}

export default App;

Properties

Name	Type	Default	Description
height	number	400	Set the height of the inbox.
itemHeight	number	50	Estimated item height. It gets measured after mount, but it helps to estimate this to limit layout shift.
ItemComponent	Component		Component to use as Notification Item. The component receives two props; index: number and data: Notification.

InlineNotification

Properties

Name	Type	Default	Description
animate	"down" | "up"
topic	string
variant	"bar" | "dot"
Component	any

SlackButton

A button to subscribe or unsubscribe a user to your Slack channel.

Registers or removes the user’s Slack token using the provided Slack App ID. Supports custom labels, styling, and redirect flow.

import * as React from "react";
import Provider from "@magicbell/react/context-provider";
import SlackButton from "@magicbell/react/slack-button";

function App(props: any) {
  return (
    <Provider token="${USER_JWT}">
      <SlackButton
        redirectUrl="https://example.com"
        appId="A06DAT80SHF"
        renderLabel={({ status, error }) =>
          error || (status === "success" ? "disable" : "enable")
        }
      />
    </Provider>
  );
}

export default App;

Properties

Name	Type	Default	Description
appId *	string		The Slack App ID used to initiate the installation flow.
className	string		Additional class names to apply to the button.
onClick	(event: Event) => void | false		Called when the button is clicked. Return false to prevent the install flow.
redirectUrl	string	location.href	Optional URL to redirect the user to after completing the Slack OAuth flow. Defaults to the current origin.
renderLabel	((props: { status: Status; error: string | null;}) => any)	({ status }) => status === 'success' ? 'discard' : 'enable'	Custom render function for the button label. Receives the current install status and any error message.

UserPreferences

A preferences management component that lets users toggle notification channels per category.

Properties

Name	Type	Default	Description
className	string		Additional class names to apply to the root container element.

WebPushButton

A button to subscribe or unsubscribe a user to Web Push Notifications.

Uses the Push API to register or remove the user’s subscription. The user stays on the page; no redirect is involved. Requires a configured service worker. Supports custom labels, styling, and ref forwarding.

To enable web push, your service worker must import MagicBell’s script:

importScripts('https://assets.magicbell.io/web-push-notifications/sw.js');

import * as React from "react";
import Provider from "@magicbell/react/context-provider";
import WebPushButton from "@magicbell/react/webpush-button";

function App(props: any) {
  return (
    <Provider token="${USER_JWT}">
      <WebPushButton
        renderLabel={({ status, error }) =>
          error || (status === "success" ? "disable" : "enable")
        }
      />
    </Provider>
  );
}

export default App;

Properties

Name	Type	Default	Description
className	string		Additional class names to apply to the button.
onClick	(event: Event) => void | false		Called when the button is clicked. Return false to prevent the subscription flow.
renderLabel	((props: { status: Status; error: string | null;}) => any)	({ status }) => status === 'success' ? 'discard' : 'enable'	Custom render function for the button label. Receives the current install status and any error message.
serviceWorkerPath	string	/sw.js	Path to your custom service worker file. Defaults to /sw.js. The service worker must include MagicBell’s web push script via importScripts(...).