Skip to content
Block Kit for React
Esc
↑↓navigate↵open⌘Jpreview
On this page

BlockKitProvider

Every prop of the provider that connects rendered blocks to your app.

<BlockKitProvider> holds the state of every input rendered beneath it, and is where interactions reach your code. It’s optional: without one, blocks render and inputs work, but actions go nowhere.

import { BlockKitProvider, Message } from "@nkootstra/block-kit";

<BlockKitProvider
  onAction={(action, { views, message, state }) => {}}
  onSubmit={(payload, { views }) => {}}
  onOptions={(payload) => ({ options: [] })}
  resolvers={{ user: (id) => users[id]?.name }}
>
  <Message blocks={blocks} />
</BlockKitProvider>;

One provider can hold several surfaces. Each action still carries the message or view it came from.

Props

Handlers

PropType
onAction?(action: BlockAction, context: ActionContext) => void

Called for every action: a click, a selection, a date picked. action is exactly the payload's actions[0], with text objects normalized as Slack echoes them (emoji: true, verbatim: false). context has state, views and, for actions in a message, message.

Type(action: BlockAction, context: ActionContext) => void
onPayload?(payload: BlockActionsPayload, context: PayloadContext) => void

The same actions, wrapped in the full block_actions payload your request URL would receive: team, user, container, response_url and state. Use it to forward actions to an existing app.

Type(payload: BlockActionsPayload, context: PayloadContext) => void
onSubmit?(payload, context: { views }) => SubmitResult | Promise<SubmitResult>

Called with a view_submission payload when a modal's submit button is pressed and its inputs are valid. Return a response_action (errors, update, push or clear), or nothing to close the modal. If it throws or rejects, the modal stays open.

Type(payload, context: { views }) => SubmitResult | Promise<SubmitResult>
onClose?(payload) => void

Called with a view_closed payload when a modal's close button is pressed.

Type(payload) => void
onOptions?(payload: BlockSuggestionPayload) => OptionsResponse | Promise<OptionsResponse>

Answers an external_select's block_suggestion request with { options } or { option_groups }, as your options load URL would. Without it, external selects accept a typed value on Enter.

Type(payload: BlockSuggestionPayload) => OptionsResponse | Promise<OptionsResponse>
onStateChange?(state: StateValues) => void

Called whenever an input value changes, with the full state.values.

Type(state: StateValues) => void

Data

PropType
resolvers?Resolvers

Look up names for user, channel and usergroup ids, and profiles for the card a user mention opens. See Mentions and resolvers.

TypeResolvers
mentionHref?(mention: MentionRef) => string | undefined

Your app's page for a resolved mention, given its type ("user", "channel" or "usergroup") and id. Channel and user group mentions become links to it; a user mention's profile card links its name.

Type(mention: MentionRef) => string | undefined
linkComponent?ComponentType<LinkProps>

Renders every link from the payload, e.g. your router's link component. It gets href, className, children, and target and rel for links that open a new tab.

TypeComponentType<LinkProps>
Defaulta plain anchor
emoji?EmojiOptions

imageUrl(unified) builds the image URL for a standard emoji; custom maps workspace emoji names to image URLs or alias:<name>. See Emoji.

TypeEmojiOptions
DefaultApple emoji from jsDelivr
identity?PayloadIdentity

team, user, apiAppId, token, triggerId, responseUrl and isEnterpriseInstall stamped onto the payloads the provider builds, and teamName, the workspace name a contact card shows (no payload carries it). They ship in the page, so use placeholder or test values: never a real verification token or response_url.

TypePayloadIdentity
DefaultPlaceholder ids such as T00000000 and U00000000
errors?Record<string, string>

Validation errors keyed by block_id, shown under input blocks: the shape of response_action: "errors".

TypeRecord<string, string>

mentionHref and linkComponent connect a message to your app’s own pages and router: see Linking to your app.

URL safety

A message’s URLs come from whoever wrote it, so the renderer only follows the ones that can’t run code. Links (mrkdwn, rich text, markdown, data tables, plan and task card sources, videos, attachments, and what mentionHref returns), link buttons and overflow options keep an http, https, mailto or slack URL, or a relative one like /settings or #notes. Any other scheme, such as javascript:, data: or vbscript:, is dropped: the link keeps its text but has no href, and a button still sends its action but opens nothing. The check strips the spaces, tabs and newlines a browser would strip first, so \tjava\nscript: is caught too.

linkComponent only ever receives a URL that passed this check, so it doesn’t need its own. An image block’s image_url goes through the check too, and also keeps blob: and data:image/ URLs. Other image URLs (icons, avatars, thumbnails) are left as they are: an image can’t run a script.

A relative URL resolves against the page that renders the message, not against Slack, so a relative link opens a page of your own app and a relative image makes the viewer’s browser request that path from your server, with their cookies. See Untrusted input for what that means for payloads you don’t trust.

Display

PropType
surface?"message" | "modal" | "home"

The surface loose <Blocks> are laid out for. <Message>, <Modal> and <HomeTab> set their own.

Type"message" | "modal" | "home"
Default"message"
theme?"light" | "dark"

Forces a colour scheme for everything inside. Without it, the page's data-theme or the system preference applies. See Theming.

Type"light" | "dark"
timeZone?string

IANA zone for <!date> tokens, message times and the datetimepicker, which shows and reads the picked date and time in it. A date picker doesn't use it (it sends a calendar day with no zone), and a time picker names its zone with its own timezone field.

Typestring
DefaultThe viewer's zone; UTC for the datetimepicker
childrenReactNode

The surfaces to render.

TypeReactNode

ActionContext

The second argument to onAction.

PropType
state?StateValues

The value of every input on the surface when the action happened, keyed by block_id, then action_id, like view.state.values.

TypeStateValues
views?ViewsApi

Open, push, update, close and clear modals, and publish the Home tab.

TypeViewsApi
message?MessageApi | undefined

Set for actions in a <Message>. update({ blocks, text }) replaces the message; delete() removes it.

TypeMessageApi | undefined

ViewsApi

The calls your app makes with Slack’s views.* methods. A modal opened this way renders above the provider’s children and gets its own input state. Slack allows three modals in the stack.

PropType
open?(view) => string

views.open: replaces any open modals with this one. Returns the new view id.

Type(view) => string
push?(view) => string

views.push: stacks a modal on top of the current one. Returns the new view id.

Type(view) => string
update?(view, target?: { viewId?; externalId? }) => void

views.update: swaps a modal's content, keeping input values whose block_id and action_id are unchanged. Targets the top modal unless you pass viewId or externalId.

Type(view, target?: { viewId?; externalId? }) => void
close?() => void

Closes the top modal.

Type() => void
clear?() => void

Closes every open modal.

Type() => void
publish?(view) => void

views.publish: replaces the content of the <HomeTab> under this provider.

Type(view) => void

Last updated on