Linking to your app
Send mentions to your own pages and route every link in a message through your router, with examples for Next.js, React Router, TanStack Start, Astro and Vite.
In Slack, clicking #general opens the channel. Outside Slack, in a help desk, an archive or an
agent dashboard, a mention has nowhere to go unless you say where. Two props on
<BlockKitProvider> connect a message to your app:
mentionHrefgives a mention a page in your app.linkComponentrenders every link in the message, so your router handles it.
Neither changes how anything looks. Click the mentions and the link below to see what your app would get:
The @Ada Lovelace mention opens the profile card, as in Slack; its name links to your page.
Link mentions to your pages
mentionHref gets a resolved mention’s type ("user", "channel" or "usergroup") and Slack
id, and returns a URL in your app, or undefined to leave that mention as it is:
<BlockKitProvider
resolvers={resolvers}
mentionHref={({ type, id }) => `/${type}s/${id}`}
>
- Channel and user group mentions become links to that URL, in the same tab.
- A user mention still opens the profile card when clicked, as in Slack, and the name in the card links to that URL.
- Mentions that
resolverscan’t name, and broadcasts like@here, stay as they are: Slack shows them without a link too.
A linked mention looks exactly like one without a link; only the cursor changes.
Only some mentions
Return undefined for anything your app has no page for. Here only people have pages:
const mentionHref = ({ type, id }: MentionRef) => (type === "user" ? `/people/${id}` : undefined);
Route links through your router
Without linkComponent, every link is a plain <a>. Give it your router’s link component to keep
navigation inside your app. It renders every link that comes from the payload:
- links in mrkdwn, rich text and the markdown block, and dates with a link
- links in data tables, and plan and task card sources
- video titles, attachment authors and titles
- mentions linked by
mentionHref
It gets LinkProps: href, className, children, and target and rel for links that open
a new tab, as Slack’s do. Pass className on: it carries block-kit’s styling. The href has
already passed the renderer’s URL safety check, so a
javascript: URL never reaches it. The examples check for // as well as /, because //host/path
is a link to another site, not a path in your app. A link in mrkdwn or rich text sits in a <span>
that opens Slack’s link hover card, so your component doesn’t have to forward pointer events; the
card’s Open in new tab button opens the URL in a new tab with window.open, not through your
component. Route your own paths and leave everything else a plain <a>:
import { Link } from "react-router";
import type { LinkProps } from "@nkootstra/block-kit";
export function AppLink({ href, className, target, rel, children }: LinkProps) {
if (href.startsWith("/") && !href.startsWith("//")) {
return (
<Link to={href} className={className} target={target} rel={rel}>
{children}
</Link>
);
}
return (
<a href={href} className={className} target={target} rel={rel}>
{children}
</a>
);
}
React Router’s and TanStack Router’s Link take to; Next.js’s next/link takes href.
In your framework
mentionHref, linkComponent and resolvers are functions, so they have to be created where React
runs in the browser. Each example below ran in a production build of that framework, with the links
navigating client-side where the framework routes on the client.
Only the functions live in the browser file, never what they look names up with. The names come from
your server: pass them in as plain { id: name } props, or point useWebApiResolvers at a resolver
relay with httpResolverClient. A WebClient and the bot token never belong in that file. See
Keep the bot token on the server
and examples/nextjs.
Put the provider in a "use client" file. Your page can stay a Server Component and import
<Message> directly.
// app/providers.tsx
"use client";
import Link from "next/link";
import { BlockKitProvider, type LinkProps, type Resolvers } from "@nkootstra/block-kit";
import type { ReactNode } from "react";
function AppLink({ href, className, target, rel, children }: LinkProps) {
if (href.startsWith("/") && !href.startsWith("//")) {
return (
<Link href={href} className={className} target={target} rel={rel}>
{children}
</Link>
);
}
return (
<a href={href} className={className} target={target} rel={rel}>
{children}
</a>
);
}
const resolvers: Resolvers = {
user: (id) => users.get(id),
channel: (id) => channels.get(id),
};
export function Providers({ children }: { children: ReactNode }) {
return (
<BlockKitProvider
resolvers={resolvers}
mentionHref={({ type, id }) => `/${type}s/${id}`}
linkComponent={AppLink}
>
{children}
</BlockKitProvider>
);
}// app/page.tsx (a Server Component)
import { Message } from "@nkootstra/block-kit";
import { Providers } from "./providers";
export default async function Page() {
const message = await getMessage();
return (
<Providers>
<Message message={message} timeZone="UTC" />
</Providers>
);
}Import @nkootstra/block-kit/styles.css in app/layout.tsx.
In framework mode and in a single-page app alike, pass the props to the provider in your route.
React Router’s Link takes to.
// app/AppLink.tsx
import { Link } from "react-router";
import type { LinkProps } from "@nkootstra/block-kit";
export function AppLink({ href, className, target, rel, children }: LinkProps) {
if (href.startsWith("/") && !href.startsWith("//")) {
return (
<Link to={href} className={className} target={target} rel={rel}>
{children}
</Link>
);
}
return (
<a href={href} className={className} target={target} rel={rel}>
{children}
</a>
);
}// app/routes/message.tsx
import { BlockKitProvider, Message } from "@nkootstra/block-kit";
import { AppLink } from "../AppLink";
export default function MessageRoute({ loaderData }: Route.ComponentProps) {
return (
<BlockKitProvider
resolvers={resolvers}
mentionHref={({ type, id }) => `/${type}s/${id}`}
linkComponent={AppLink}
>
<Message message={loaderData.message} timeZone="UTC" />
</BlockKitProvider>
);
}Import @nkootstra/block-kit/styles.css in app/root.tsx.
Pass the props to the provider in your route component. TanStack Router’s Link takes to; a
string href type-checks without a cast, and matches your $id routes at runtime.
// src/AppLink.tsx
import { Link } from "@tanstack/react-router";
import type { LinkProps } from "@nkootstra/block-kit";
export function AppLink({ href, className, target, rel, children }: LinkProps) {
if (href.startsWith("/") && !href.startsWith("//")) {
return (
<Link to={href} className={className} target={target} rel={rel}>
{children}
</Link>
);
}
return (
<a href={href} className={className} target={target} rel={rel}>
{children}
</a>
);
}// src/routes/messages.$ts.tsx
import { createFileRoute } from "@tanstack/react-router";
import { BlockKitProvider, Message } from "@nkootstra/block-kit";
import { AppLink } from "../AppLink";
export const Route = createFileRoute("/messages/$ts")({ component: MessagePage });
function MessagePage() {
const message = Route.useLoaderData();
return (
<BlockKitProvider
resolvers={resolvers}
mentionHref={({ type, id }) => `/${type}s/${id}`}
linkComponent={AppLink}
>
<Message message={message} timeZone="UTC" />
</BlockKitProvider>
);
}Import @nkootstra/block-kit/styles.css in src/routes/__root.tsx.
Write a React component that owns the provider, and render it as an island. Astro has no
client-side router link for React, so links are plain anchors: without <ClientRouter /> they
load a new page, and with it they navigate client-side.
// src/components/SlackMessage.tsx
import {
BlockKitProvider,
type LinkProps,
Message,
type SlackMessageLike,
} from "@nkootstra/block-kit";
import "@nkootstra/block-kit/styles.css";
function AppLink({ href, className, target, rel, children }: LinkProps) {
return (
<a href={href} className={className} target={target} rel={rel}>
{children}
</a>
);
}
export default function SlackMessage({ message }: { message: SlackMessageLike }) {
return (
<BlockKitProvider
resolvers={resolvers}
mentionHref={({ type, id }) => `/${type}s/${id}`}
linkComponent={AppLink}
>
<Message message={message} timeZone="UTC" />
</BlockKitProvider>
);
}---
// src/pages/messages/[ts].astro
import SlackMessage from "../../components/SlackMessage";
const message = await getMessage(Astro.params.ts);
---
<SlackMessage client:load message={message} />A single-page app has no server boundary: pass the props straight to the provider. With React
Router as the router, AppLink is the one from the React Router tab.
// src/main.tsx
import { createRoot } from "react-dom/client";
import { BrowserRouter, Route, Routes } from "react-router";
import { BlockKitProvider, Message } from "@nkootstra/block-kit";
import "@nkootstra/block-kit/styles.css";
import { AppLink } from "./AppLink";
function MessagePage() {
return (
<BlockKitProvider
resolvers={resolvers}
mentionHref={({ type, id }) => `/${type}s/${id}`}
linkComponent={AppLink}
>
<Message message={message} />
</BlockKitProvider>
);
}
createRoot(document.getElementById("root")!).render(
<BrowserRouter>
<Routes>
<Route path="/" element={<MessagePage />} />
<Route path="/channels/:id" element={<ChannelPage />} />
</Routes>
</BrowserRouter>,
);In the server-rendered examples, timeZone keeps the message’s time the same on the server and in
the browser; see Server rendering.
Rewrite external links
linkComponent sees every URL before it renders, so it can change it. For example, send links that
leave your app through a redirect page:
function AppLink({ href, className, target, rel, children }: LinkProps) {
const internal = href.startsWith("/") && !href.startsWith("//");
const url = internal ? href : `/out?to=${encodeURIComponent(href)}`;
return (
<a href={url} className={className} target={target} rel={rel}>
{children}
</a>
);
}
/out is an open redirect unless it checks where it sends people: anyone can link to
/out?to=https://phishing.example with your domain in front. Have the page show the destination and
ask before leaving, or only redirect to an http or https URL whose host you allow.