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 environmentuserId*string
The ID of the user for which to retrieve a feeduserTokenstring
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 Knocki18nI18nContent
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 displayeddefaultFeedOptionsFeedClientOptions
Set defaults for `tenant`, `has_tenant`, `source`, `archived` to scope all subsequent feed queriescolorModeColorMode
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 clientfeedClientFeed
The instance of the authenticated FeeduseFeedStoreUseStore<FeedStoreState>
A zustand store containing the FeedStoreStatecolorModeColorMode
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 clientsetConnectionStatusfunction
A function to set the connection statuserrorLabelstring
An error message about the connection statussetErrorLabelfunction
A function to set an error labelactionLabelstring
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
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.
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` hookchildren*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 renderonItemClickfunction
The function to be invoked when the notification cell is clickedonButtonClickfunction
The function to be invoked when a button rendered in the notification cell is clickedavatarReactNode
Render a custom avatar for the feed itemarchiveButtonReactNode
Render a custom archive button for the feed itemchildrenReactNode
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.
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 clickedbadgeCountTypeenum
One of `unseen` | `unread` | `all` to determine which count to display
Slack components
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
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;
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.
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 environmentuserIdstring
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 withfeedChannelIdstring
The in-app feed channel ID, obtained from the Knock dashboardoptionsFeedClientOptions
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 fromselectorStateSelector<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 appredirectUrlstring
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 scopesdisconnectFromSlackfunction
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 channelisLoadingboolean
Whether the channels are loadingrefetchfunction
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 channelsloadingboolean
Whether the channels are loadingerrorstring
Error message if something went wrong; otherwise nullupdateConnectedChannels(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 botredirectUrlstring
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 URLdisconnectFromMsTeamsfunction
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 teamisLoadingboolean
Whether the teams are loadingrefetchfunction
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 fromqueryOptionsMsTeamsChannelQueryOptions
An optional map of params to control the query to the Microsoft Graph API
Returns:
dataMsTeamsChannel[]
List of partial data about each Microsoft Teams channelisLoadingboolean
Whether the Microsoft Teams channels are loadingrefetchfunction
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 channelsloadingboolean
Whether the Microsoft Teams channels are loadingerrorstring
Error message if something went wrong; otherwise nullupdateConnectedChannels(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.
SlackChannelQueryOptions
SlackChannel
SlackChannelConnection
MsTeamsTeamQueryOptions
MsTeamsChannelQueryOptions
MsTeamsTeam
MsTeamsChannel
MsTeamsChannelConnection
RecipientObject
ConnectionStatus