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*stringThe public API key for the environment
userId*stringThe ID of the user for which to retrieve a feed
userTokenstringA 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.
timeBeforeExpirationInMsnumberDetermines the amount of time in milliseconds before the token expires that the callback should be fired.
hoststringA custom API host for Knock
i18nI18nContentAn 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*stringThe channel ID of the in-app feed to be displayed
defaultFeedOptionsFeedClientOptionsSet defaults for `tenant`, `has_tenant`, `source`, `archived` to scope all subsequent feed queries
colorModeColorModeSets the theme as either light or dark mode (defaults to light)
useKnockFeed
The KnockFeedProvider exposes a useKnockFeed hook for all child components.
Returns: KnockFeedProviderState
knockKnockThe instance of the Knock client
feedClientFeedThe instance of the authenticated Feed
useFeedStoreUseStore<FeedStoreState>A zustand store containing the FeedStoreState
statusFilterStatusCurrent value of the filter status for the Feed
setStatusfunctionA function to set the current FilterStatus
colorModeColorModeThe current theme color
Example:
KnockInAppMessagesChannelProvider
Props
channelId*stringThe in-app messaging channel ID obtained from the Knock dashboard under “Integrations > Channels”. Should be a UUID.
defaultOptions*stringA set of default options to apply to all fetches for in-app messages. Here you can set common defaults, like the tenants you wish to scope messages for etc.
colorMode*stringEither light or dark to pass a theme down to components.
useInAppMessagesChannel
Only available under the KnockInAppMessagesChannelProvider.
Returns:
inAppMessagesChannelClient*stringAn in-app message client that stores the shared state of in-app messages.
colorMode*stringThe current color mode.
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*stringThe ID of the Slack channel in the Knock dashboard that the Slack application is linked to.
tenant*stringThe ID of the tenant that will be storing the Slack access token
useKnockSlackClient
The KnockSlackProvider exposes a useKnockSlackClient hook for all child components.
Returns:
connectionStatusConnectionStatusThe status of the auth connection to the given Slack client
setConnectionStatusfunctionA function to set the connection status
errorLabelstringAn error message about the connection status
setErrorLabelfunctionA function to set an error label
actionLabelstringA label that gives an action for the user to take, like 'Retry' or 'Disconnect'
setActionLabelfunctionA 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 notifcation feed.
Props
variantstringThe variant of the button; either `primary` or `secondary`. Defaults to `primary`.
loadingTextstringText to display while the button is loading.
isLoadingbooleanWhen true, will display a spinner next to the `loadingText` (if present).
isDisabledbooleanWhen true, will mark the button as disabled.
isFullWidthbooleanWhen true, will make the button occupy 100% of the parent container.
onClick*functionThe click handler to be invoked when the button is clicked.
childrenReactNodeThe text to display inside of the button.
Used to group and space multiple Button components into a single line.
Props
children*ReactNodeOne or more `Button` components
KnockI18nProvider
A provider to inject translations into components.
Props
i18nI18nContentA set of translations and a locale to use in child components via the `useTranslations` hook
children*ReactNodeOne or more `Button` components
Feed components
NotificationFeed
Props
EmptyComponent*ReactNodeThe empty component to render, when not set defaults to <EmptyFeed />.
renderItemfunctionA 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`.
renderHeaderfunctionA 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`.
onNotificationClickfunctionA custom function to be invoked when a notification cell is clicked.
onNotificationButtonClickfunctionA custom function to be invoked when an action button in a notification cell is clicked.
onMarkAllAsReadClickfunctionA custom function to be invoked when the `Mark all as read` button is clicked.
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*booleanWhether or not to show the popover.
onClose*functionThe function to be invoked when the popover is closed.
onOpenfunctionA 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.
closeOnClickOutsidebooleanWhen true, will close the popover whenever any area outside of the popover is clicked.
placementPlacementDetermines the popper-js position of the popover (defaults to `bottom-end`).
NotificationCell
Props
item*FeedItemThe feed item (notification) to render
onItemClickfunctionThe function to be invoked when the notification cell is clicked
onButtonClickfunctionThe function to be invoked when a button rendered in the notification cell is clicked
avatarReactNodeRender a custom avatar for the feed item
archiveButtonReactNodeRender a custom archive button for the feed item
childrenReactNodeA 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*functionThe function to be invoked when the IconButton is clicked
badgeCountTypeenumOne of `unseen` | `unread` | `all` to determine which count to display
Messaging components
By default, our React library exposes 3 different out of the box components: Banner, Card, and Modal. Each component maps to a message type that Knock ships.
Each of the components exports a *View component that contains granular view components that can be composed to override specific parts of the pre-built components.
Banner
Props
filtersUseInAppMessageOptionsA set of query filters
Example
Card
Props
filtersUseInAppMessageOptionsA set of query filters
Example
Modal
Props
filtersUseInAppMessageOptionsA set of query filters
Example
Slack components
Props
slackClientId*stringThe client ID of your Slack application.
redirectUrlstringThe 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*ReactNodeRender a button, either a custom one or the SlackAuthButton, to connect to Slack
SlackChannelCombobox
Props
slackChannelRecipientObject*ContainerObjectObject ID and collection of the Knock object that will store the channel data of the connected Slack channels.
showConnectedChannelTagsbooleanOptionally show tags of the Slack channels that are connected, defaults to false.
General hooks
useAuthenticatedKnockClient
Creates an authenticated Knock client.
Params
apiKey*stringThe public API key for the Knock environment
userIdstringThe userId of the user to authenticate with Knock.
userTokenstringOptional user token to authenticate requests for the current user with.
optionsAuthenticatedKnockClientOptionsA set of options to provide to the Knock instance.
Returns
Knock instance, authenticated against the user
Example
useTranslations
Exposed under KnockI18nProvider child components.
Returns:
localestringThe current locale code (defaults to `en`)
t(key: string) => stringA 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
knockKnockThe Knock instance to create the feed with
feedChannelIdstringThe in-app feed channel ID, obtained from the Knock dashboard
optionsFeedClientOptionsAn 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
feedClientFeedThe 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
Messaging hooks
useInAppMessages
A hook used to fetch in-app messages for a particular user, channel, message type triple.
Props:
messageTypestringThe key of the message type you wish to fetch messages about
optionsInAppMessagesClientOptionsA set of filtering options to apply to the message fetched from this hook
Returns:
messagesMessage[]The returned in-app messages
loadingbooleanWhether the network request is currently in-flight
networkStatusNetworkStatusGranular information about the current network status
inAppMessagesClientInAppMessagesClientA message client instance to interact with the message
Example:
Slack hooks
Exposed under KnockSlackProvider child components.
useSlackAuth
Builds a Slack authorization URL generator and a disconnect function.
Props:
slackClientIdstringThe client ID from your Slack app
redirectUrlstringThe URL to redirect back to after authorizing; should be your own application's URL
Returns:
buildSlackAuthUrlfunctionFunction to build a valid Slack URL with the necessary scopes
disconnectFromSlackfunctionFunction 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:
queryOptionsSlackChannelQueryOptionsAn optional map of params to control the query to the Slack API
Returns:
dataSlackChannel[]List of partial data about each Slack channel
isLoadingbooleanWhether the channels are loading
refetchfunctionFunction 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:
slackChannelsRecipientObjectContainerObjectThe object that holds connected Slack channesl as channel data
Returns:
dataSlackChannelConnection[]List of data about the connected Slack channels
loadingbooleanWhether the channels are loading
errorstringError message if something went wrong; otherwise null
updateConnectedChannels(connectedChannels: SlackChannelConnection[]) => void;Function to set the connected channels. Updates all connected channels for the object, does not add to the current ones.
updatingbooleanWhether the channels are currently being set
Types
I18nContent
Used to set translations available in the child components exposed under KnockFeedProvider and KnockSlackProvider. Used in the useTranslations hook.
Note: locale must be a valid locale code.
QueryOptions
SlackChannel
SlackChannelConnection
ContainerObject
ConnectionStatus