React

KDiagramLive is a typed React wrapper around the same web component used everywhere else. KDiagramPlayground adds a source editor and should be loaded only when editing is part of the experience.

Install

pnpm add @kekonic/diagrams @kekonic/diagrams-element @kekonic/diagrams-ui

Import the live styles once:

styles.css

@import "@kekonic/diagrams-ui/live.css";

Live diagram

example.tsx

import { KDiagramLive } from "@kekonic/diagrams-ui";

export function Architecture({ source }: { source: string }) {
  return (
    <KDiagramLive
      source={source}
      theme="auto"
      height={480}
      frameless
      showThemeToggle={false}
      showViewControls
      view="context"
      showViewSwitcher
      onKDiagramRender={(event) => {
        if (!event.detail.ok) console.error(event.detail.diagnostics);
      }}
      onKDiagramViewChange={(event) => {
        console.log(event.detail.view);
      }}
    />
  );
}

Changing source rerenders without remounting the viewport. For kdiagram 2 models, pass view to select a lens and showViewSwitcher for the picker (showViewControls remains pan/zoom only). The component accepts animation props including animation, autoplay, animationLoop, and showAnimationControls. Set frameless to remove the host border and panel background while keeping control props independent. Unmodified wheel scrolls the page; zoom with Ctrl/⌘ + scroll, pinch, or the toolbar. Pass options={{ zoomOnWheel: "always" }} only when the live view should consume every wheel event.

Use a ref when the host needs view methods:

example.tsx

import { useRef } from "react";
import type { KDiagramElement } from "@kekonic/diagrams-element";

const diagram = useRef<KDiagramElement>(null);

<KDiagramLive ref={diagram} source={source} />;
<button onClick={() => diagram.current?.fit()}>Fit diagram</button>;

Editable playground

Import the playground from its separate entry point so ordinary live diagrams do not pull editor and syntax-highlighting code:

styles.css

@import "@kekonic/diagrams-ui/playground.css";

example.tsx

import { KDiagramPlayground } from "@kekonic/diagrams-ui/playground";

<KDiagramPlayground source={initialSource} layout="split" height={560} showStats={false} />;

The playground supports split, stacked, and gallery layouts. It lazy-loads syntax highlighting, and accepts the same animation, autoplay, animationLoop, and showAnimationControls props as the live view. It is still a much larger and more interactive surface than a static diagram. Reserve it for tutorials, sandboxes, and authoring tools.

Server-rendered SVG

For a diagram that does not need browser interaction, render during the server or static build:

example.ts

import { renderKDiagramSvg } from "@kekonic/diagrams-ui";

const { svg, diagnostics } = await renderKDiagramSvg(source, {
  theme: "light",
  snapshotTheme: true,
});

This avoids shipping the live rendering path to the client. See SVG and static sites for trust boundaries and theme choices.