Emoji
Standard, custom and skin-toned :shortcode: emoji, and the plain_text emoji flag.
Slack sends emoji as :shortcode: text, never images, inside mrkdwn, rich text, and plain text
objects. @nkootstra/block-kit resolves each shortcode to an image the way Slack’s client does,
including workspace custom emoji and skin tone modifiers.
Standard emoji
Any shortcode from Slack’s standard set renders automatically: nothing to configure. By default, images come from the Apple emoji set on jsDelivr, matching what Slack itself uses:
<Message blocks={[{ type: "section", text: { type: "mrkdwn", text: "Ship it :rocket:" } }]} />
Override the image source with emoji.imageUrl, given a unified codepoint sequence like
1f680 (or 1f44d-1f3fd for a skin-toned variant):
<BlockKitProvider
emoji={{
imageUrl: (unified) => `https://your-cdn.example.com/emoji/${unified}.png`,
}}
>
By default every viewer’s browser fetches these images from cdn.jsdelivr.net, which then sees
their IP address and the page they’re on, and a Content Security Policy needs it in img-src. To
keep emoji on your own host, copy the image set there and point imageUrl at it.
Custom emoji
Workspace custom emoji have no fixed set: pass them as a name → URL map with emoji.custom:
<BlockKitProvider
emoji={{
custom: {
partyparrot: "https://your-cdn.example.com/emoji/partyparrot.gif",
// Aliases point at another custom emoji, or at a standard one:
dancingparrot: "alias:partyparrot",
shipit: "alias:rocket",
},
}}
>
<Message
blocks={[{ type: "section", text: { type: "mrkdwn", text: "Look at it go :partyparrot:" } }]}
/>
</BlockKitProvider>
custom[name]?string
An image URL, or "alias:<name>" pointing at another custom or standard emoji name.
stringAn unrecognized shortcode, not standard and not in custom, falls back to the literal :name:
text, exactly as Slack shows an emoji it can’t find.
Skin tones
:thumbsup::skin-tone-3: (Fitzpatrick modifiers 2–6) picks the matching variant of a standard emoji
that supports one. Modifiers on emoji without skin tone variants, or on custom emoji, are ignored: the
base emoji renders instead. In a rich_text block, an emoji element takes its tone from
skin_tone, or from a modifier in its unicode ({ name: "wave", unicode: "1f44b-1f3fd" } draws
:wave::skin-tone-4:), as Slack does. The image’s alt text and tooltip name the tone.
Sizing
Every emoji renders at Slack’s inline size (22px, matching 15px body text) by default. Components that
take an emojiSize prop, such as <Mrkdwn> and <Text>, pass it straight through, useful for a larger emoji in
a header or a smaller one in dense UI:
<Mrkdwn text="Big wave :wave:" emojiSize={32} />
plain_text and the emoji flag
A plain_text text object converts :shortcode: to emoji images by default, same as mrkdwn. Set
emoji: false to show the literal colons-and-name text instead, useful for values that happen to
contain a colon, like a code or a time range, that shouldn’t be treated as emoji:
{ type: "plain_text", text: "Status: :done:", emoji: false }
emoji has no effect on mrkdwn text objects: mrkdwn always converts shortcodes; use verbatim (see
mrkdwn) if you need to suppress other mrkdwn formatting instead.









