Building notification feeds with React

Our @knocklabs/react library comes pre-built with a real-time feed component that you can drop into your application. In this guide, you'll find common recipes to help you work with the pre-built Knock feed UI element.

See a live demo of our pre-built in-app feed UI element ->

Getting started

To use this example, you'll need an account on Knock, as well as an in-app feed channel with a workflow that produces in-app feed messages. You'll also need:

• A public API key for the Knock environment (set as KNOCK_PUBLIC_API_KEY)
• The channel ID for the in-app feed (set as KNOCK_FEED_CHANNEL_ID)

Installing dependencies

Rendering a notification feed (prebuilt UI element)

To add a real-time notifications feed to your product, you can use the out-of-the-box components that the @knocklabs/react library offers.

Common recipes

Building custom UI

You can build headless notifications UI on top of our hooks. Learn more.

Setting an action_url on the notification cell

You can pass a value in the Action URL field of your notification template and the KnockFeedProvider will attach a redirect handler if action_url is not empty.

Adding an onClick handler to the notification cell

You can customize the click handler for the notification cell as follows:

Both the NotificationFeed and the NotificationFeedPopover take a onNotificationClick prop.

Rendering a different notification cell in the feed

You can customize the rendering of a notification cell in the feed by overriding the renderItem prop.

Overriding the avatar

You can customize the Avatar component rendered within the NotificationCell by passing a different avatar component into the NotificationCell in the renderItem function passed to the feed:

Using read instead of seen for the badge count

Marking messages as read on the popover opening

Using dark mode

The feed supports an optional colorMode prop, that defaults to light but can be set as dark for dark mode support.

Adding inline actions

For more advanced use cases, you may need to provide inline actions on your notifications. The NotificationCell component accepts a children prop in order for you to render actions. You'll need to override the renderItem prop on the NotificationFeed or NotificationFeedPopover to render the custom notification cell.

Using action buttons

We ship Button and ButtonGroup components, which have a complementary set of styling for the rest of the feed. You can render the buttons in a button group so that they'll be grouped together, or can render them individually.

Note: remember to call event.stopPropagation in your onClick handler to stop the notification onClick handler from being invoked.

Targeting a specific workflow to have buttons

A common use case is to only show action buttons for certain workflows. You can achieve this via the item.source property, which exposes a WorkflowSource:

You can find a full list of the props available for the Button component here.

Handling cross-browser feed synchronization

The Feed optionally supports an __experimentalCrossBrowserUpdates option under the defaultFeedOptions which will opt into using a BroadcastChannel to keep multiple browser viewing contexts (windows, tabs) in sync for the same user feed.

You can see a demo of this behavior here:

Automatically disconnecting sockets from inactive tabs

Optionally, you can configure the Feed to disconnect socket connections with inactive tabs after a brief delay. If the tab becomes active again, the socket will reconnect to continue receiving real-time updates.

Customizing the feed styling

The complete theme that controls the look and feel of the feed components can be customized for theme in a few different ways:

1. Customizing the CSS variables. The feed is written using CSS variables, which you can override to better match the look and feel of your product. The best way to see the possible CSS variables in use is to look at the theme.css source code.

2. Bringing your own CSS. It's possible to override the Knock CSS entirely to customize the look and feel of the feed. All of the feed classes are unique and start with rnf-. You can see the classes in use by looking at the source code of the components.

Setting custom translations

You can set custom translations for the components inside the feed by passing the i18n property to the KnockProvider component. You can provide a partial or full set of translations to be used following the expected I18nContent type.

Note: the default locale used in the components will be en. No other translations are provided out-of-the-box.

Filtering/scoping a feed

A feed can be scoped by any of the parameters that are accepted on the feed endpoint via the FeedClientOptions set in the defaultFeedOptions for the KnockFeedProvider component, or via the useNotifications hook.

You can read more in this guide on feed filtering.

Related links

• @knocklabs/react library reference
• @knocklabs/client library reference