Custom blocks
Render your own block and element types, or replace a built-in one.
Every block and element is looked up by its type in a registry. Add an entry to render a type the package doesn’t know, or replace an entry to change how a built-in type looks.
Unknown types otherwise render as a placeholder that names the type.
A block’s JSON comes from whoever wrote the payload, so check a field before you rely on it, as
the examples below do with state, max, URLs and nesting.
Add a block
A block component receives the block’s JSON, its blockId and its index:
import { blockComponents, Mrkdwn, type BlockProps } from "@nkootstra/block-kit";
interface StatusBlock {
type: "status";
state: "up" | "down";
text: string;
}
function Status({ block }: BlockProps<StatusBlock>) {
// `state` comes from the payload: map it to a class you know, rather than putting it in one.
const modifier = block.state === "down" ? "status--down" : "status--up";
return (
<div className={`status ${modifier}`}>
<Mrkdwn text={block.text} />
</div>
);
}
blockComponents.status = Status;
Register it once, before rendering, for example next to the stylesheet import. Now { "type": "status", "state": "up", "text": "All systems *operational*" } renders with your component, wherever it appears: messages, modals, the Home tab, and blocks nested in containers.
The block is wrapped in <div class="sbk-block sbk-block--status" data-block-id="…">, so it gets Slack’s spacing between blocks.
Add an element
Element components receive the element’s JSON and the blockId of the block they’re in. Use useBlockKit to report actions:
import { elementComponents, useBlockKit, type ElementProps } from "@nkootstra/block-kit";
interface RatingElement {
type: "rating";
action_id: string;
max: number;
}
function Rating({ element, blockId }: ElementProps<RatingElement>) {
const { dispatch } = useBlockKit();
// `max` comes from the payload: clamp it, so a huge value can't hang the page.
const max = Math.min(Math.max(Math.trunc(Number(element.max)) || 0, 0), 10);
return (
<span>
{Array.from({ length: max }, (_, i) => (
<button
key={i}
type="button"
onClick={() =>
dispatch({
type: "rating",
action_id: element.action_id,
block_id: blockId,
value: String(i + 1),
})
}
>
★
</button>
))}
</span>
);
}
elementComponents.rating = Rating;
The element works in actions, input and section accessories, and its clicks reach onAction like any built-in element’s. For an input, call setValue(blockId, element.action_id, { type: "rating", value }) (also from useBlockKit()) on change so the value appears in state and the view_submission payload.
Replace a built-in
Assign over an existing entry, keeping the original to fall back to:
import { blockComponents } from "@nkootstra/block-kit";
import { PrivateImage } from "./PrivateImage"; // your component for images behind your auth
const BuiltInImage = blockComponents.image;
// Compare the parsed host: a prefix check like startsWith("https://internal.") also matches
// https://internal.attacker.example.
const isInternal = (url: string | undefined) => {
try {
return url !== undefined && new URL(url).hostname === "internal.example.com";
} catch {
return false;
}
};
blockComponents.image = (props) =>
isInternal(props.block.image_url) ? <PrivateImage {...props} /> : <BuiltInImage {...props} />;
Rendering blocks yourself
Inside a custom block, render nested blocks and elements with <Block> and <Element> so they go through the registries too:
import { createContext, useContext } from "react";
import { Block, type BlockProps, type Json } from "@nkootstra/block-kit";
const PanelDepth = createContext(0);
function Panel({ block }: BlockProps<{ type: "panel"; blocks: Json[] }>) {
// A payload can nest panels as deep as it likes: stop at a depth your design needs.
const depth = useContext(PanelDepth);
if (depth >= 3 || !Array.isArray(block.blocks)) return null;
return (
<PanelDepth.Provider value={depth + 1}>
<section className="panel">
{block.blocks.map((child, i) => (
<Block key={i} block={child} index={i} />
))}
</section>
</PanelDepth.Provider>
);
}