In-App UI

React

SDK

Reference

React SDK API reference

Complete API reference for the Knock React SDK.

In this section, you'll find the complete documentation for the components exposed in @knocklabs/react, including the props available.

Note: You can see a reference for the methods available for the Knock class, as well as a Feed instance under the client JS docs.

Context

`KnockProvider`

The top-level provider that connects to Knock with the given API key and authenticates a user.

Props

Accepts KnockProviderProps

apiKey*string

The public API key for the environment

userId*string

The ID of the user for which to retrieve a feed

userTokenstring

A JWT that identifies the authenticated user, signed with the private key provided in the Knock dashboard. Required to secure your production environment. Learn more.

onUserTokenExpiring(oldToken: string) => Promise<string | void>

A callback to provide that will fire before a user Token expires. By default will fire 30s before the token is set to expire. If a string is returned from the resolved promise, that will be used as the new user token.

timeBeforeExpirationInMsnumber

Determines the amount of time in milliseconds before the token expires that the callback should be fired.

hoststring

A custom API host for Knock

i18nI18nContent

An optional set of translations to override the default `en` translations used in the feed components

`useKnockClient`

The KnockProvider exposes a useKnockClient hook for all child components.

Returns: Knock, an instance of the Knock JS client.

Example:

`KnockFeedProvider`

The feed-specific provider that connects to a feed for that user. Must be a child of the KnockProvider.

Props

Accepts KnockFeedProviderProps:

feedId*string

The channel ID of the in-app feed to be displayed

defaultFeedOptionsFeedClientOptions

Set defaults for `tenant`, `has_tenant`, `source`, `archived` to scope all subsequent feed queries

colorModeColorMode

Sets the theme as either light or dark mode (defaults to light)

`useKnockFeed`

The KnockFeedProvider exposes a useKnockFeed hook for all child components.

Returns: KnockFeedProviderState

knockKnock

The instance of the Knock client

feedClientFeed

The instance of the authenticated Feed

useFeedStoreUseStore<FeedStoreState>

A zustand store containing the FeedStoreState

colorModeColorMode

The current theme color

Example:

`KnockSlackProvider`

The Slack-specific provider that connects to a Slack workspace for the given tenant. Must be a child of the KnockProvider.

Props

Accepts KnockSlackProviderProps

knockSlackChannelId*string

The ID of the Slack channel in the Knock dashboard that the Slack application is linked to.

tenant*string

The ID of the tenant that will be storing the Slack access token

`KnockMsTeamsProvider`

The Microsoft Teams-specific provider that connects to Microsoft Teams for the given tenant. Must be a child of the KnockProvider.

Props

Accepts KnockMsTeamsProviderProps

knockMsTeamsChannelId*string

The ID of the Microsoft Teams channel in the Knock dashboard that the Microsoft Teams bot is linked to.

tenantId*string

The ID of the Knock tenant that will be storing the Microsoft Entra tenant ID

`useKnockSlackClient`

The KnockSlackProvider exposes a useKnockSlackClient hook for all child components.

Returns:

connectionStatusConnectionStatus

The status of the auth connection to the given Slack client

setConnectionStatusfunction

A function to set the connection status

errorLabelstring

An error message about the connection status

setErrorLabelfunction

A function to set an error label

actionLabelstring

A label that gives an action for the user to take, like 'Retry' or 'Disconnect'

setActionLabelfunction

A function to set the action label

Example:

General components

`Button`

A generic Button component that can be used to add action buttons to items in a notification feed.

Props

variantstring

The variant of the button; either `primary` or `secondary`. Defaults to `primary`.

loadingTextstring

Text to display while the button is loading.

isLoadingboolean

When true, will display a spinner next to the `loadingText` (if present).

isDisabledboolean

When true, will mark the button as disabled.

isFullWidthboolean

When true, will make the button occupy 100% of the parent container.

onClick*function

The click handler to be invoked when the button is clicked.

childrenReactNode

The text to display inside of the button.

`ButtonGroup`

Used to group and space multiple Button components into a single line.

Props

children*ReactNode

One or more `Button` components

`KnockI18nProvider`

A provider to inject translations into components.

Props

i18nI18nContent

A set of translations and a locale to use in child components via the `useTranslations` hook

children*ReactNode

One or more `Button` components

Feed components

`NotificationFeed`

Props

EmptyComponent*ReactNode

The empty component to render, when not set defaults to <EmptyFeed />.

renderItemfunction

A function invoked per `FeedItem` to be rendered that should return a cell to be rendered in the feed. Useful when you want to render a custom feed cell. Defaults to rendering a `NotificationCell`.

renderHeaderfunction

A function invoked that returns a header to be rendered in the feed. Useful when you want to render a custom header. Defaults to rendering a `NotificationFeedHeader`.

onNotificationClickfunction

A custom function to be invoked when a notification cell is clicked.

onNotificationButtonClickfunction

A custom function to be invoked when an action button in a notification cell is clicked.

onMarkAllAsReadClickfunction

A custom function to be invoked when the `Mark all as read` button is clicked.

initialFilterStatusFilterStatus

The initial filter applied by the NotificationFeed (e.g., `FilterStatus.All` or `FilterStatus.Unread`). If unspecified, defaults to 'All'.

`NotificationFeedPopover`

Renders a NotificationFeed in a floating popover, rendered by popper-js.

Props

Accepts the same base props as NotificationFeed, and overrides with the following:

isVisible*boolean

Whether or not to show the popover.

onClose*function

The function to be invoked when the popover is closed.

onOpenfunction

A function that's invoked whenever the feed popover is opened, useful for updating any items in view and marking them as read, seen, or archived.

buttonRef*RefObject<HTMLElement>

A ref of the button to position the popover adjacent to.

closeOnClickOutsideboolean

When true, will close the popover whenever any area outside of the popover is clicked.

placementPlacement

Determines the popper-js position of the popover (defaults to `bottom-end`).

`NotificationCell`

Props

item*FeedItem

The feed item (notification) to render

onItemClickfunction

The function to be invoked when the notification cell is clicked

onButtonClickfunction

The function to be invoked when a button rendered in the notification cell is clicked

avatarReactNode

Render a custom avatar for the feed item

archiveButtonReactNode

Render a custom archive button for the feed item

childrenReactNode

A set of children to render inside of the cell, will be rendered under the main content in a `rnf-notification-cell__child-content` div. Useful for rendering action buttons.

`NotificationIconButton`

Renders a notification bell icon, with a badge showing the number of unseen items present in the notification feed.

Props

onClick*function

The function to be invoked when the IconButton is clicked

badgeCountTypeenum

One of `unseen` | `unread` | `all` to determine which count to display

Slack components

`SlackAuthButton`

Props

slackClientId*string

The client ID of your Slack application.

redirectUrlstring

The URL of your application to return to once Slack authorization is complete.

onAuthenticationComplete(authenticationResult: 'authComplete' | 'authFailed') => void;

An optional callback function you can pass to this component that will execute upon completion of the authentication flow. Takes one argument of the authentication result for you to handle in your callback.

`SlackAuthContainer`

Props

actionButton*ReactNode

Render a button, either a custom one or the SlackAuthButton, to connect to Slack

`SlackChannelCombobox`

Props

slackChannelsRecipientObject*RecipientObject

Object ID and collection of the Knock object that will store the channel data of the connected Slack channels.

queryOptionsSlackChannelQueryOptions

An optional map of params to control the query to the Slack API

Microsoft Teams components

`MsTeamsAuthButton`

Props

msTeamsBotId*string

The ID of your Microsoft Teams bot.

redirectUrlstring

The URL of your application to return to once Microsoft Teams authorization is complete.

onAuthenticationComplete(authenticationResult: 'authComplete' | 'authFailed') => void;

`MsTeamsAuthContainer`

Props

actionButton*ReactNode

Render a button, either a custom one or the MsTeamsAuthButton, to connect to Microsoft Teams

`MsTeamsChannelCombobox`

Props

msTeamsChannelsRecipientObject*RecipientObject

Object ID and collection of the Knock object that will store the channel data of the connected Microsoft Teams channels.

General hooks

`useAuthenticatedKnockClient`

Creates an authenticated Knock client.

Params

apiKey*string

The public API key for the Knock environment

userIdstring

The userId of the user to authenticate with Knock.

userTokenstring

Optional user token to authenticate requests for the current user with.

optionsAuthenticatedKnockClientOptions

A set of options to provide to the Knock instance.

Returns

Knock instance, authenticated against the user

Example

`useTranslations`

Exposed under KnockI18nProvider child components.

Returns:

localestring

The current locale code (defaults to `en`)

t(key: string) => string

A helper function to get the value of a translation from the current `Translations`.

Feed hooks

`useNotifications`

Creates a Feed instance for the provided Knock client which creates a stateful, real-time connection to Knock to build in-app experiences.

Params

knockKnock

The Knock instance to create the feed with

feedChannelIdstring

The in-app feed channel ID, obtained from the Knock dashboard

optionsFeedClientOptions

An optional set of feed client options to pass to the created Feed instance

Returns

Feed instance

Example

`useNotificationStore`

Given a Feed will return reactive access to the FeedStateStore. Can optionally accept a selector to retrieve a fine-grained slice of state from the store.

Params

feedClientFeed

The feed instance to select content from

selectorStateSelector<FeedStoreState>

An optional selector to limit the state slice returned from the store. Defaults to returning all state.

Returns

FeedStoreState

Example

Slack hooks

Exposed under KnockSlackProvider child components.

useSlackAuth

Builds a Slack authorization URL generator and a disconnect function.

Props:

slackClientIdstring

The client ID from your Slack app

redirectUrlstring

The URL to redirect back to after authorizing; should be your own application's URL

Returns:

buildSlackAuthUrlfunction

Function to build a valid Slack URL with the necessary scopes

disconnectFromSlackfunction

Function to disconnect from Slack which revokes the access token and removes it from the tenant in Knock

useSlackChannels

This hook will continually fetch partial data about Slack channels from a given workspace up to the max limit given.

Props:

queryOptionsSlackChannelQueryOptions

An optional map of params to control the query to the Slack API

Returns:

dataSlackChannel[]

List of partial data about each Slack channel

isLoadingboolean

Whether the channels are loading

refetchfunction

Function to fetch the channels again

useConnectedSlackChannels

This hook returns partial data about the Slack channels that are present on the given recipient object's channel data. These are the Slack channels that would be notified with this object as a recipient of a workflow.

Props:

slackChannelsRecipientObjectRecipientObject

The object that holds connected Slack channels as channel data

Returns:

dataSlackChannelConnection[]

List of data about the connected Slack channels

loadingboolean

Whether the channels are loading

errorstring

Error message if something went wrong; otherwise null

updateConnectedChannels(connectedChannels: SlackChannelConnection[]) => Promise<void>;

Function to set the connected channels. Updates all connected channels for the object, does not add to the current ones.

updatingboolean

Whether the channels are currently being set

Microsoft Teams hooks

Exposed under KnockMsTeamsProvider child components.

`useMsTeamsAuth`

Builds a Microsoft Teams authorization URL generator and a disconnect function.

Props:

msTeamsBotIdstring

The ID of your Microsoft Teams bot

redirectUrlstring

The URL to redirect back to after authorizing; should be your own application's URL

Returns:

buildMsTeamsAuthUrlfunction

Function to build a valid Microsoft Teams authorization URL

disconnectFromMsTeamsfunction

Function to disconnect from Microsoft Teams which removes the Microsoft Entra tenant ID from the tenant in Knock

`useMsTeamsTeams`

This hook will continually fetch partial data about Microsoft Teams teams within a given Microsoft Entra tenant up to the max limit given.

Props:

queryOptionsMsTeamsTeamQueryOptions

An optional map of params to control the query to the Microsoft Graph API

Returns:

dataMsTeamsTeam[]

List of partial data about each team

isLoadingboolean

Whether the teams are loading

refetchfunction

Function to fetch the teams again

`useMsTeamsChannels`

This hook will continually fetch partial data about Microsoft Teams channels within a given team.

Props:

teamIdstring

The ID of the team to fetch channels from

queryOptionsMsTeamsChannelQueryOptions

An optional map of params to control the query to the Microsoft Graph API

Returns:

dataMsTeamsChannel[]

List of partial data about each Microsoft Teams channel

isLoadingboolean

Whether the Microsoft Teams channels are loading

refetchfunction

Function to fetch the Microsoft Teams channels again

`useConnectedMsTeamsChannels`

This hook returns partial data about the Microsoft Teams channels that are present on the given recipient object's channel data. These are the Microsoft Teams channels that would be notified with this object as a recipient of a workflow.

Props:

msTeamsChannelsRecipientObjectRecipientObject

The object that holds connected Microsoft Teams channels as channel data

Returns:

dataMsTeamsChannelConnection[]

List of data about the connected Microsoft Teams channels

loadingboolean

Whether the Microsoft Teams channels are loading

errorstring

Error message if something went wrong; otherwise null

updateConnectedChannels(connectedChannels: MsTeamsChannelConnection[]) => Promise<void>;

Function to set the connected Microsoft Teams channels. Updates all connected channels for the object, does not add to the current ones.

updatingboolean

Whether the Microsoft Teams channels are currently being set

Types

`I18nContent`

Used to set translations available in the child components exposed under KnockFeedProvider, KnockSlackProvider, and KnockMsTeamsProvider. Used in the useTranslations hook.

Note: locale must be a valid locale code.