merslim

A slimmer mermaid — SVG-first diagram renderer for mermaid-style syntax. 14 native diagram types, zero mermaid runtime dependency.

| | | |---|---| | Bundle | ~160 KB minified ESM (vs. mermaid's ~3 MB lazy-loaded / ~7 MB full) | | Runtime deps | dagre only | | Peer deps | react ^18 \|\| ^19, react-dom ^18 \|\| ^19 | | Mermaid | none — parsers and renderers are native | | Outputs | Standalone SVG, PNG (via canvas), and plain-text ASCII (Unicode box-drawing) | | License | MIT |

Why

Mermaid is great, but it's heavy, opaque, and not easy to extend. merslim re-implements the popular subset of mermaid syntax with:

• A small, typed intermediate representation (IR) you can build programmatically — no need to round-trip through text if you have structured data.
• A pluggable renderer registry. Diagrams are React components; lazy-loaded by type so you only pay for what you use.
• A serializer that walks the live DOM, inlines getComputedStyle() values onto a clone, and emits a self-contained SVG that opens identically in browsers, Inkscape, and Office.
• No vendor lock-in to a single visual style — every renderer is ~150–400 lines of plain React/SVG, easy to fork.

Supported diagram types

flowchart · sequenceDiagram · erDiagram · classDiagram · stateDiagram-v2 · gantt · timeline · pie · quadrantChart · journey · mindmap · architecture-beta · C4Context (Container / Component / Deployment) · gitGraph

Install

npm install merslim

Quick start

import { DiagramRenderer, bootstrapDiagramRenderers } from 'merslim';

bootstrapDiagramRenderers(); // call once at app startup

const source = `
flowchart LR
  A[Edit] --> B{Render}
  B --> C[Export]
`;

export function App() {
  return <DiagramRenderer source={source} />;
}

With the export toolbar

import { useRef } from 'react';
import {
  DiagramRenderer,
  DiagramExportToolbar,
  type RendererHandle,
} from 'merslim';

export function MyDiagram({ source }: { source: string }) {
  const handleRef = useRef<RendererHandle | null>(null);

  return (
    <div className="group relative">
      <DiagramRenderer source={source} handleRef={handleRef} />
      <DiagramExportToolbar
        source={() => handleRef.current?.getSvgElement() ?? null}
        className="absolute top-2 right-2 opacity-0 group-hover:opacity-100"
      />
    </div>
  );
}

The toolbar gives you four buttons — copy SVG, copy PNG, download SVG, download PNG — all routed through the same standalone-SVG serializer. Pass an optional asciiSource to add two more (copy ASCII, download .txt); see ASCII output below.

Headless / SSR

If you only need an SVG string (e.g. to generate diagrams at build time for an MDX blog), skip the React component entirely:

import { parseToIR, flowchartToSvg, type FlowchartIR } from 'merslim';

const result = await parseToIR(`
flowchart LR
  A --> B
`);

if (result.ok && result.type === 'flowchart') {
  const svg = flowchartToSvg(result.ir as FlowchartIR, { dark: false });
  // write to disk, embed, ship to a CDN...
}

Two builder flavors. For each graph-shaped diagram there's a one-call convenience builder (flowchartToSvg, classToSvg, erToSvg) that runs layout internally, and a position-taking power-user builder (buildFlowchartSvg(ir, positions, opts)) for callers who want custom layout. Chart-shaped diagrams (pie, quadrant, journey, gantt, timeline, c4, architecture, gitgraph) are one-call already. See examples/headless/generate.ts for the full pattern.

ASCII output

Every one of the 14 diagram types also renders to plain text using Unicode box-drawing characters — useful for terminals, CI logs, code review comments, plain-text emails, and LLM tool outputs.

import { sourceToAscii } from 'merslim';

const text = await sourceToAscii(`
flowchart LR
  A[Start] --> B --> C[End]
`);
console.log(text);
//  ┌───────┐    ┌─────┐    ┌─────┐
//  │ Start │────▶  B  │────▶ End │
//  └───────┘    └─────┘    └─────┘

If you already have an IR (e.g. from parseToIR or hand-built), use the synchronous asciiFromIR(ir) instead:

import { asciiFromIR, parseToIR } from 'merslim';

const result = await parseToIR(source);
if (result.ok) {
  const text = asciiFromIR(result.ir);
}

Per-type builders are also exported when you only need one: buildFlowchartAscii, buildSequenceAscii, buildErAscii, buildClassAscii, buildStateAscii, buildMindmapAscii, buildGanttAscii, buildJourneyAscii, buildPieAscii, buildTimelineAscii, buildQuadrantAscii, buildGitGraphAscii, buildArchitectureAscii, buildC4Ascii.

In the toolbar

Pass an asciiSource function to <DiagramExportToolbar/> to surface two extra buttons ("ASCII" copy / ".TXT" download):

import {
  DiagramRenderer,
  DiagramExportToolbar,
  asciiFromIR,
  parseToIR,
  type DiagramIR,
  type RendererHandle,
} from 'merslim';

export function MyDiagram({ source }: { source: string }) {
  const handleRef = useRef<RendererHandle | null>(null);
  const [ir, setIr] = useState<DiagramIR | null>(null);

  useEffect(() => {
    parseToIR(source).then((r) => setIr(r.ok ? r.ir : null));
  }, [source]);

  return (
    <div className="group relative">
      <DiagramRenderer source={source} handleRef={handleRef} />
      <DiagramExportToolbar
        source={() => handleRef.current?.getSvgElement() ?? null}
        asciiSource={() => (ir ? asciiFromIR(ir) : null)}
      />
    </div>
  );
}

Build your own IR

The parser is one way to produce an IR; you can produce one any way you like. If you have structured data (a list of orders, a service topology, a customer journey) you can skip mermaid syntax entirely:

import { flowchartToSvg, type FlowchartIR } from 'merslim';

const ir: FlowchartIR = {
  type: 'flowchart',
  direction: 'LR',
  nodes: [
    { id: 'a', label: 'Order received', kind: 'start' },
    { id: 'b', label: 'Validate payment', kind: 'decision' },
    { id: 'c', label: 'Ship', kind: 'end' },
  ],
  edges: [
    { source: 'a', target: 'b' },
    { source: 'b', target: 'c', label: 'paid' },
  ],
};

const svg = flowchartToSvg(ir, { dark: false });

Selective renderer registration

bootstrapDiagramRenderers() is a convenience that registers all 14 native renderers (lazy-loaded, so unused ones stay out of your initial bundle). If you only need a subset and want to skip even the lazy chunks, call register() directly:

import { register, DiagramRenderer } from 'merslim';

register({
  type: 'flowchart',
  loader: () =>
    import('merslim').then((m) => ({ default: m.FlowchartRenderer })),
});
// Now <DiagramRenderer/> only knows about flowcharts. Any other diagram type
// surfaces a "no renderer registered" error.

If you already have an IR and want to skip the source-string parser entirely, the 14 renderers are also exported directly and can be mounted as standalone components — <FlowchartRenderer ir={ir} dark={dark}/>, <PieRenderer/>, <SequenceRenderer/>, etc.

Dark mode

Pass a dark prop to <DiagramRenderer/>, or use the helper to track a .dark class on <html>:

import { isDarkMode, watchDarkMode } from 'merslim';

const [dark, setDark] = useState(isDarkMode);
useEffect(() => watchDarkMode(setDark), []);

API surface

Components

| Export | Purpose | |---|---| | <DiagramRenderer source dark handleRef onError/> | Parses a source string, dispatches to the matching renderer, exposes a RendererHandle ref. | | <DiagramExportToolbar source asciiSource filenameBase pngScale .../> | Copy/download toolbar — 4 buttons by default (SVG/PNG copy + download), plus 2 more (ASCII copy + .txt download) when asciiSource is supplied. | | <FlowchartRenderer/> <SequenceRenderer/> <ERRenderer/> <ClassRenderer/> <StateRenderer/> <GanttRenderer/> <TimelineRenderer/> <PieRenderer/> <QuadrantRenderer/> <JourneyRenderer/> <MindmapRenderer/> <ArchitectureRenderer/> <C4Renderer/> <GitGraphRenderer/> | Direct-mount renderer per diagram type. Same RendererProps<T> signature: { ir, dark, handleRef }. Use these when you already have an IR. |

Parser / IR

| Export | Type | Purpose | |---|---|---| | parseToIR(source) | (string) => Promise<ParseResult> | Mermaid syntax → typed IR. On success, narrows to { ok: true, type: DiagramType, ir: DiagramIR }. | | detectDiagramType(source) | (string) => Promise<RecognizedDiagramType \| null> | Lightweight first-line check. Returns null for empty input, 'unsupported' for unrecognized headers. |

Builders (headless)

| Convenience (auto-layout) | Power-user (explicit positions) | |---|---| | flowchartToSvg(ir, opts) | buildFlowchartSvg(ir, positions, opts) | | classToSvg(ir, opts) | buildClassSvg(ir, positions, opts) | | erToSvg(ir, opts) | buildErSvg(ir, positions, opts) | | — | buildStateSvg(ir, { topLevel, children }, opts) | | — | buildMindmapSvg(ir, positions, opts) |

Plus the chart-shaped diagrams which never need positions: buildPieSvg, buildQuadrantSvg, buildJourneySvg, buildGanttSvg, buildTimelineSvg, buildArchitectureSvg, buildC4Svg, buildGitGraphSvg.

All builders take a final { dark, padding } options object and return a self-contained SVG string with role="img" and an aria-label.

ASCII builders (headless)

| Export | Type | Purpose | |---|---|---| | sourceToAscii(source) | (string) => Promise<string \| null> | One-call mermaid source → text. null only when parsing fails. | | asciiFromIR(ir) | (DiagramIR) => string \| null | Synchronous IR → text dispatch. Covers all 14 diagram types. | | build{Type}Ascii(ir) | (IR) => string | Per-type builder. One per diagram type — same naming as the SVG builders. |

Export pipeline

| Export | Purpose | |---|---| | toSvgString(source, opts) | Serialize any SvgSource to a standalone SVG string. | | svgToPngBlob(svg, opts) | Rasterize an SVG string to a PNG Blob. | | downloadSvg / downloadPng / downloadText | Trigger a file download (SVG, PNG, or plain text). | | copySvgToClipboard / copyPngToClipboard / copyTextToClipboard | Write SVG (text), PNG (image), or arbitrary text to the clipboard. | | getSvgDimensions(svg) | Best-effort intrinsic size from viewBox / attrs. |

Registry

| Export | Purpose | |---|---| | register({ type, loader }) | Register a renderer for a diagram type. | | bootstrapDiagramRenderers() | One-shot registration of all built-in renderers. | | getRenderer(type) / hasRenderer(type) | Introspect the registry. |

Examples

• examples/playground/ — Vite + React playground with all 14 diagram types, a live source editor, dark-mode toggle, and the export toolbar (SVG + PNG + ASCII). npm install && npm run dev (or npm run build for a static dist/ that opens directly from file://).
• examples/headless/ — Node script that emits one self-contained SVG and one Unicode-box-drawing .txt per diagram type. npm install && npm start.
• examples/react/App.tsx — Minimal React snippet showing the same component wiring (including ASCII toolbar buttons) without the playground chrome.

Development

npm install
npm run type-check   # tsc --noEmit
npm test             # vitest run
npm run build        # tsup → dist/ (ESM + CJS + .d.ts)

Notes & limitations

• The built-in renderers use a handful of Tailwind utility classes for surrounding chrome (loading / error states). The diagrams themselves are pure SVG and render correctly without Tailwind; only the wrapper container styling looks bare. PRs to make this opt-out are welcome.
• parseToIR is asynchronous because some builders (gantt, timeline) defer parsing work. Today the body is synchronous but the signature is stable.

Mermaid compatibility

merslim parses a curated subset of mermaid syntax. The full contract is enforced by test/compatCorpus.ts — every entry there is a parse-time test that runs in CI.

Known gaps (parse but produce a partial IR, or fail outright):

| Diagram | Gap | |---|---| | flowchart | Multi-target shorthand A & B --> C & D | | flowchart | Trapezoid shape [/Foo\] (falls back to rect) | | flowchart | <br/> in labels treated as literal text, not a line break | | sequence | loop/alt/opt/par blocks parse but render flat (no visual nesting) | | sequence | autonumber keyword accepted but not honored | | sequence | Bidirectional <<->> arrow | | class | Generics class Container~T~ | | class | Cardinality labels "1" --> "*" | | class | namespace { ... } blocks | | state | Parallel/concurrent regions (-- separator) | | state | <<choice>>/<<fork>>/<<join>> pseudo-states | | gantt | excludes/todayMarker/tickInterval accepted but not modeled |

If you hit a case not listed here, add it to the corpus as a known-gap entry — that converts an issue into an executable spec.

License

MIT. See LICENSE.