Diagram SDK
Viewer Mode & Embeds
Embedding read-only interactive diagrams in Next.js documentation sites, blogs, and dashboards.
<Diagram mode="viewer" /> renders your architecture as a lightweight, read-only canvas. It allows visitors to pan, wheel-zoom, and inspect services without showing editing toolbars or property sidebars.
1. Live Interactive Documentation Embed
Try interacting with the live architecture embed below using your mouse or trackpad:
- Pan: Click and drag to pan across the board.
- Zoom: Use your mouse wheel or the floating
+/-zoom pill in the bottom-left. - Copy JSON: Click the copy button in the top-right to copy the underlying diagram data.
Loading diagram canvas...
2. Next.js App Router Integration (SSR Safe)
Because canvas rendering relies on browser APIs (window, HTMLCanvasElement), use Next.js dynamic imports with ssr: false:
"use client";
import React from "react";
import dynamic from "next/dynamic";
import type { DiagramData } from "@filekit-studio/diagram";
// 1. Dynamic import with SSR disabled
const Diagram = dynamic(
() => import("@filekit-studio/diagram").then((mod) => mod.Diagram),
{
ssr: false,
loading: () => (
<div className="w-full h-full flex items-center justify-center bg-gray-50 dark:bg-zinc-900 text-neutral-400 font-mono text-xs">
Loading architecture canvas...
</div>
),
}
);
interface ArchitectureViewerProps {
data: DiagramData;
}
export function ArchitectureViewer({ data }: ArchitectureViewerProps) {
return (
// 2. Bounded height container (required for autoFit calculation)
<div className="w-full h-[400px] rounded-xl overflow-hidden border border-neutral-200 dark:border-zinc-800 shadow-sm">
<Diagram
data={data}
mode="viewer" // Read-only canvas without editing toolbars
autoFit={true} // Automatically computes zoom to fit within container
interactive={true} // Allows readers to pan and wheel-zoom
showCopyButton={true} // Copies diagram JSON in 1 click
showZoomControls={true} // Shows floating zoom +/- pill in bottom-left
canvasBackground="#f0f4f8"
gridStyle="dots"
/>
</div>
);
}3. Recommended Viewer Props Reference
| Prop | Type | Default | Description |
|---|---|---|---|
mode | "viewer" | "editor" | "editor" | Set to "viewer" for read-only documentation embeds. |
autoFit | boolean | true | Centers the graph and calculates optimal zoom level to fit inside container. |
interactive | boolean | true | Allows visitors to pan and wheel-zoom. Set to false for static images. |
showCopyButton | boolean | true | Renders a 1-click JSON copy button in the top-right header. |
showZoomControls | boolean | true | Renders a floating zoom + / - / fit pill in the bottom-left. |
canvasBackground | string | "#ffffff" | Background color behind the canvas. |
gridStyle | "dots" | "cross" | "lines" | "none" | "dots" | Background grid pattern. |
theme | "light" | "dark" | "light" | Canvas color theme. |
4. Bounded Container Rule
<Diagram autoFit={true} /> measures the parent DOM element's width and height to calculate the exact viewport scale:
// ✅ Correct: Parent has a defined height (e.g. h-[400px] or h-full)
<div className="w-full h-[400px]">
<Diagram data={json} mode="viewer" autoFit={true} />
</div>
// ❌ Incorrect: Undefined height causes canvas to measure 0px
<div>
<Diagram data={json} mode="viewer" autoFit={true} />
</div>