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
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.
(action: BlockAction, context: ActionContext) => voidonPayload?(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.
(payload: BlockActionsPayload, context: PayloadContext) => voidonSubmit?(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.
(payload, context: { views }) => SubmitResult | Promise<SubmitResult>onClose?(payload) => void
Called with a view_closed payload when a modal's close button is pressed.
(payload) => voidonOptions?(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.
(payload: BlockSuggestionPayload) => OptionsResponse | Promise<OptionsResponse>onStateChange?(state: StateValues) => void
Called whenever an input value changes, with the full state.values.
(state: StateValues) => voidData
resolvers?Resolvers
Look up names for user, channel and usergroup ids, and profiles for the card a user mention opens. See Mentions and resolvers.
ResolversmentionHref?(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.
(mention: MentionRef) => string | undefinedlinkComponent?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.
ComponentType<LinkProps>a plain anchoremoji?EmojiOptions
imageUrl(unified) builds the image URL for a standard emoji; custom maps workspace emoji names to image URLs or alias:<name>. See Emoji.
EmojiOptionsApple emoji from jsDelivridentity?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.
PayloadIdentityT00000000 and U00000000errors?Record<string, string>
Validation errors keyed by block_id, shown under input blocks: the shape of response_action: "errors".
Record<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
surface?"message" | "modal" | "home"
The surface loose <Blocks> are laid out for. <Message>, <Modal> and <HomeTab> set their own.
"message" | "modal" | "home""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.
"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.
stringThe viewer's zone; UTC for the datetimepickerchildrenReactNode
The surfaces to render.
ReactNodeActionContext
The second argument to onAction.
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.
StateValuesviews?ViewsApi
Open, push, update, close and clear modals, and publish the Home tab.
ViewsApimessage?MessageApi | undefined
Set for actions in a <Message>. update({ blocks, text }) replaces the message; delete() removes it.
MessageApi | undefinedViewsApi
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.
open?(view) => string
views.open: replaces any open modals with this one. Returns the new view id.
(view) => stringpush?(view) => string
views.push: stacks a modal on top of the current one. Returns the new view id.
(view) => stringupdate?(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.
(view, target?: { viewId?; externalId? }) => voidclose?() => void
Closes the top modal.
() => voidclear?() => void
Closes every open modal.
() => voidpublish?(view) => void
views.publish: replaces the content of the <HomeTab> under this provider.
(view) => void