Build your own feed UI (headless)

To implement your own UI for Feed in your react application we provide context providers and hooks.

If you are not using any of the In-build UI components while designing your custom UI for feed, you can use @suprsend/react-core SDK. These hooks and context providers are available in both @suprsend/react-core and @suprsend/react SDK’s. Integration steps mentioned in this guide are also same for both.

Pre-Requisite

Integrate SuprSendProvider as it is needed for creating SuprSend Client and authenticating user.

Installation

npm install @suprsend/react-core

yarn add @suprsend/react-core

In @suprsend/react-core v1.0.0, we have changed the pageInfo object data. Please refer to Migration guide for more details.

Integration

SuprSendFeedProvider

This provider internally creates InApp feed client instance and also removes it on unmounting. This should be called inside SuprSendProvider. FeedClient can be accessed using useFeedClient hook.

import { SuprSendProvider, SuprSendFeedProvider } from '@suprsend/react-core';
// import { SuprSendProvider, SuprSendFeedProvider } from '@suprsend/react'; // if you use our inbuilt react components

function Example() {
  return (
    <SuprSendProvider publicApiKey={YOUR_KEY} distinctId={YOUR_DISTINCT_ID}>
      <SuprSendFeedProvider>Your Feed Component</SuprSendFeedProvider>
    </SuprSendProvider>
  );
}

interface SuprSendFeedProviderProps {
  tenantId?: string;
  pageSize?: number;
  stores?: IStore[] | null;
  host?: { socketHost?: string, apiHost?: string };
  reachability?: boolean;
}

tenantId defaults to the active tenant set in SuprSendProvider, else the default tenant. Passing it here pins the feed instance to that tenant — it takes priority over the active tenant and the feed ignores later tenant changes. Without it, the feed re-initializes automatically whenever the active tenant changes. If you are passing tenantId in feed, make sure it matches scope.tenant_id passed while creating userToken else error will be thrown due to scope mismatching. reachability defaults to false. Pass it to track whether the feed is working for this user. See Tracking reachability.

useFeedClient

This hook is used to get Feed client instance. Using this instance you can access feed methods like mark seen, archive, read etc. Use this hook inside SuprSendFeedProvider.

import {useFeedClient} from '@suprsend/react-core';
// import { useFeedClient } from '@suprsend/react'; // if you use our inbuilt react components

function MyComponent() {
const feedClient = useFeedClient();

return (
  <p
    onClick={() => {
      feedClient.markAsSeen(notificationId);
    }}
  >
    Click Me
  </p>
);
}

useFeedData

This hook returns react state that contains notification store data which includes notifications list and other meta data. This state gets updated internally when there is any update in store. Use this state to render UI in your application. Use this hook inside SuprSendFeedProvider.

import {useFeedData} from "@suprsend/react-core"
// import { useFeedData } from '@suprsend/react'; // if you use our inbuilt react components


function MyComponent() {
  const feedData = useFeedData();

  const notificationsList = feedData.notifications;
  return <div>{notificationsList.map(notification)=><p>{notification.n_id}</p>}</div>;
}

Tracking reachability

Reachability tells you whether the feed is working for this user right now. It combines three checks into one status — the browser is online, the feed socket is live, and the feed API is reachable — so you can show your own dot or banner when new notifications may be missing. It’s off by default. Pass reachability to SuprSendFeedProvider, then read it with useFeed() inside that provider. reachability is React state, so your component re-renders when the overall status, socket.status, api.status or api.authError changes. It’s undefined when the provider doesn’t have reachability set. The status is one of ONLINE, CONNECTING, DEGRADED, AUTH_ERROR, OFFLINE or UNKNOWN. The React Inbox component renders a coloured dot and a banner for each status. Here’s how to render the same states in a custom feed:

Online
Connecting
Connection issue
Authentication error
Offline

Inbox with a green connected dot on the bell and beside the panel title

import {
  SuprSendProvider,
  SuprSendFeedProvider,
  useFeed,
  ReachabilityStatus,
} from "@suprsend/react-core";

// Same dot and banner mapping as the React Inbox component
const states = {
  ONLINE:     { dot: "green",   text: "" },
  CONNECTING: { dot: "spinner", text: "Connecting…" },
  DEGRADED:   { dot: "amber",   text: "There seems to be a connection issue. New notifications may get delayed or missed." },
  AUTH_ERROR: { dot: "amber",   text: "Not able to fetch notifications due to authentication or permission issue." },
  OFFLINE:    { dot: "grey",    text: "You're offline. Reload the page to update notifications when your connection is back." },
  UNKNOWN:    { dot: "none",    text: "" },
};

function App() {
  return (
    <SuprSendProvider
      publicApiKey={"YOUR_PUBLIC_API_KEY"}
      distinctId={"YOUR_DISTINCT_ID"}
    >
      <SuprSendFeedProvider reachability>
        <ConnectionStatus />
      </SuprSendFeedProvider>
    </SuprSendProvider>
  );
}

function ConnectionStatus() {
  const { reachability } = useFeed();
  const status = reachability?.status ?? ReachabilityStatus.UNKNOWN;
  const state = states[status];

  return (
    <>
      <span className={`feed-dot feed-dot--${state.dot}`} />
      {state.text && <div className="feed-banner">{state.text}</div>}
    </>
  );
}

interface IFeedReachability {
  status: ReachabilityStatus;
  socket: {
    status: ChannelStatus;
    lastConnectedAt?: number;
    lastDisconnectedAt?: number;
    disconnectReason?: string;
    reconnectAttempts?: number;
  };
  api: {
    status: ChannelStatus;
    lastSuccessAt?: number;
    lastFailureAt?: number;
    authError?: boolean;
  };
  lastChangedAt: number;
}

status is one of these values:

`status`	Meaning
`OFFLINE`	The browser reports no internet connection.
`AUTH_ERROR`	The browser is online, but the API answered the initial feed load with `401` or `403`.
`DEGRADED`	The socket, the API, or both are `DOWN`.
`CONNECTING`	The socket, the API, or both are `CONNECTING`.
`ONLINE`	The socket and the API are both `UP`.
`UNKNOWN`	The browser is online but neither the socket nor the API has been used yet.

For the full IFeedReachability shape, when the value changes and how each connection is tracked, see Tracking reachability in the JavaScript SDK.

Example

import {
  SuprSendProvider,
  SuprSendFeedProvider,
  useFeedData,
  useFeedClient,
} from "@suprsend/react-core";

function Example() {
  return (
    <SuprSendProvider
      publicApiKey={"YOUR_PUBLIC_API_KEY"}
      distinctId={"YOUR_DISTINCT_ID"}
    >
      <SuprSendFeedProvider>
        <MyFeedComponent />
      </SuprSendFeedProvider>
    </SuprSendProvider>
  );
}

function MyFeedComponent() {
  const feedData = useFeedData();
  const feedInstance = useFeedClient();

  if (!feedData) return null;
  if (feedData.apiStatus === "LOADING") return <p>Loading Data</p>;
  if (feedData.apiStatus === "SUCCESS" && !feedData?.notifications?.length) {
    return <p>No Notifications</p>;
  }
  if (feedData.notifications) {
    return (
      <div>
        <div>
          {feedData.notifications.map((notification) => {
            return (
              <div
                key={notification.n_id}
                onClick={() => {
                  feedInstance.markAsRead(notification.n_id);
                }}
              >
                {notification.n_id}
              </div>
            );
          })}
        </div>
        {feedData.apiStatus === "FETCHING_MORE" ? (
          <p>Loading More</p>
        ) : (
          <div>
            {feedData.pageInfo.hasMore && (
              <button
                onClick={() => {
                  feedInstance.fetchNextPage();
                }}
              >
                Next
              </button>
            )}
          </div>
        )}
      </div>
    );
  }
  return null;
}

Using built-in components in headless implementation

We exported few inbuilt components you can use to save time while building your own UI. If you are using @suprsend/react-core and want to use these components please remove that package and install @suprsend/react, integration steps remain unchanged other than changing import statement.

NotificationCard component

This is single notification card component. It will be handy if you want to implement your own UI but want to just use our notification card as it has a bit complex logic and UI.

import { NotificationCard } from '@suprsend/react';

<NotificationCard notificationData={data} />

interface NotificationCardProps {
  notificationData: IRemoteNotification;
  notificationClickHandler?: (notificationData: IRemoteNotification) => void;
  notificationComponent?: React.FC<CustomNotificationCard>;
  hideAvatar?: boolean;
  themeType?: ThemeType;
  primaryActionClickHandler?: (notification: IRemoteNotification) => void;
  secondaryActionClickHandler?: (notification: IRemoteNotification) => void;
  theme?: INotificationCardTheme;
}

Please refer Customising CSS styles section to view typedefs for INotificationCardTheme.

BodyMarkdown component

This is simple div element but also supports rendering of markdown language. Read more about the component.

Sample Notification JSON Structure

{
  "tenant_id": "default",
  "is_expiry_visible": false,
  "seen_on": 1754346745613,
  "read_on": 1754346745613,
  "is_pinned": false,
  "archived": false,
  "created_on": 1753966489304,
  "n_category": "transactional",
  "interacted_on": 1754346745613,
  "n_id": "01K1G8SBGS4A1QG2CGYSVXQ517",
  "message": {
    "schema": "1.0",
    "header": "Your invoice for {{event.billing_month}} is ready",
    "text": "An invoice of **{{event.amount}}** has been generated for your workspace {{event.workspace_name}}.",
    "subtext": {
      "text": "View full billing history",
      "action_url": "https://app.suprsend.com/billing/history"
    },
    "avatar": {
      "avatar_url": "https://cdn-icons-png.flaticon.com/512/3144/3144456.png",
      "action_url": "https://app.suprsend.com/settings"
    },
    "url": "https://app.suprsend.com/billing/{{event.invoice_id}}",
    "extra_data": "{\n  \"workspace\": \"{{event.workspace_name}}\"\n}",
    "tags": [
      "billing",
      "finance"
    ],
    "expiry": {
      "format": "absolute",
      "expiry_type": "fixed",
      "is_expiry_visible": true,
      "value": "2025-09-30T23:59:59Z"
    },
    "is_pinned": true,
    "is_expiry_enabled": true,
    "actions": [
      {
        "url": "https://app.suprsend.com/billing/{{event.invoice_id}}",
        "name": "View Invoice"
      },
      {
        "url": "https://app.suprsend.com/billing/pay/{{event.invoice_id}}",
        "name": "Pay Now"
      }
    ]
  }
}

Fields and its description Top-level Fields

Field	Type	Description
`n_id`	string	Unique notification ID for a message.
`n_category`	string	Category of the notification. Used to fetch and apply category-level preferences (for example, `transactional`, `marketing`). You can also use categories to group notifications in different tabs.
`created_on`	number	Timestamp (epoch ms) when the notification reached the inbox.
`seen_on`	number	Timestamp (epoch ms) when the notification was first seen.
`read_on`	number	Timestamp (epoch ms) when the notification was marked as read using the `markAsRead` method.
`interacted_on`	number	Timestamp (epoch ms) when the user clicked or interacted with the notification.
`message`	object	Payload containing the actual notification content and metadata.
`tenant_id`	string	Tenant identifier. Used to identify the tenant in a multi-tenant setup.
`is_pinned`	boolean	Whether the notification is pinned in the inbox. Pinned notifications remain fixed at the top of the inbox feed. Commonly used for critical messages that should not scroll down as new notifications arrive.
`archived`	boolean	Whether the notification has been archived by the user. Archived notifications are hidden from the inbox feed by default unless you explicitly pass `archived: true` in the store query (store config).
`is_expiry_visible`	boolean	Whether the notification’s expiry is visible to the user. Expiry details are found inside the `message` object. Useful when you want notifications to auto-delete after a certain time.

message Object Fields

Field	Type	Description
`schema`	string	Schema version for the message format.
`header`	string	Main title/header of the notification.
`text`	string	Body text of the notification; supports Markdown and HTML content. Default format is markdown.
`subtext`	object	Secondary text with optional `action_url`. Is visible below the main text. Generally used to show additional information or footer text.
`avatar`	object	Avatar image shown with the notification, generally used to show sender’s profile picture; can include an action link.
`url`	string	URL where user will be redirected when they click the notification.
`extra_data`	string	JSON string for passing additional data that can be used to design custom notification card UI.
`tags`	array	List of tags to classify the notification (for example, `feature_launch`, `mentions`). Generally used to filter and organize notifications inside multiple tabs.
`is_expiry_enabled`	boolean	Whether expiry handling is enabled for this notification. Expiry is set for notifications that are supposed to auto delete after a certain time (for example, upcoming maintenances, events, etc.). Used to send notifications like upcoming maintenances, events, etc.
`expiry`	object	Expiry configuration (format, type, visibility, value) set when `is_expiry_enabled` is true.
`is_pinned`	boolean	Whether this message should pin at top of the notification feed. Generally used to send critical notifications to the user that you don’t want to go down when new notifications are added.
`actions`	array	List of call-to-action buttons (each with `url` and `name`).

You can understand more about usage and details of message fields in it’s template documentation.

Developer Resources

Updates and Versioning

Authentication

Security

SDKs and APIs

Features

Testing

Monitoring and Logging

Pre-Requisite

Installation

Integration

SuprSendFeedProvider

useFeedClient

useFeedData

Tracking reachability

Example

Using built-in components in headless implementation

NotificationCard component

BodyMarkdown component

Sample Notification JSON Structure

​Pre-Requisite

​Installation

​Integration

​SuprSendFeedProvider

​useFeedClient

​useFeedData

​Tracking reachability

​Example

​Using built-in components in headless implementation

​NotificationCard component

​BodyMarkdown component

​Sample Notification JSON Structure

Pre-Requisite

Installation

Integration

SuprSendFeedProvider

useFeedClient

useFeedData

Tracking reachability

Example

Using built-in components in headless implementation

NotificationCard component

BodyMarkdown component

Sample Notification JSON Structure