Features

• DBML in, diagram out — parses schemas with @dbml/core; tables become draggable nodes with PK/FK badges, types, notes, and a nullability dot (filled = not null, hollow = nullable).
• Crow's-foot notation — MySQL-Workbench-style edges: identifying (solid) vs non-identifying (dashed), cardinality, and optionality, all inferred from the DBML.
• Pluggable layout — zero-dependency built-in layout, or opt into dagre / elkjs for crossing minimization. Content-sized nodes with configurable min/max width.
• Flexible edges — column-anchored (default) or floating table-to-table connections that follow tables as they move.
• Themeable — light/dark presets plus per-token CSS variables (in a cascade layer) and custom fonts.
• Interactive — drag tables, persist positions, hover an edge or column to highlight the relationship, one-click auto-layout.
• Imperative API — control the viewport (fitView, zoom, center) and export via a ref.
• Export — save the diagram as PNG or SVG.
• Typed & dual-format — ships TypeScript types, ESM + UMD.

Install

npm install dbml-erd-viewer @xyflow/react react react-dom

react, react-dom, and @xyflow/react are peer dependencies — install them alongside the library.

Parsing DBML in the browser? Also install @dbml/core:

npm install @dbml/core   # only if you pass the `dbml` prop

@dbml/core is a large (~2.6 MB gzipped) parser, so it is an optional peer dependency and is imported on demand — code-split into its own async chunk, so it is never part of your entry/main bundle and browsers only download it if a dbml string is actually parsed at runtime. If you parse your schema elsewhere (server, build step) and pass the result via the schema prop, the parser chunk is never fetched.

Usage

import { DbmlViewer } from 'dbml-erd-viewer';
import 'dbml-erd-viewer/styles.css'; // bundles the required React Flow base styles

const dbml = `
Table users {
  id int [pk, increment]
  username varchar [not null, unique]
}

Table posts {
  id int [pk]
  user_id int [ref: > users.id]
  title varchar
}
`;

export default function App() {
  return (
    <div style={{ width: '100%', height: 600 }}>
      <DbmlViewer dbml={dbml} showMiniMap />
    </div>
  );
}

The viewer fills its parent, so give the wrapping element an explicit height.

Relationship notation

Edges follow MySQL Workbench's EER diagram (crow's-foot) notation:

| Visual | Meaning | | ------------------------------ | ----------------------------------------------------------------- | | Solid line | Identifying relationship — the FK is part of the child's primary key | | Dashed line | Non-identifying relationship — the FK is not part of the primary key | | Crow's foot (<) | "Many" side (the child table that holds the foreign key) | | Double bar (‖) | "One and only one" — a not null foreign key | | Bar + ring (⊣O) | "Zero or one" — a nullable foreign key |

These are derived automatically from the DBML: cardinality from the >/-/< ref operator, identifying vs non-identifying from primary-key membership (including composite [pk] indexes), and the "one" side's optionality from the foreign-key column's nullability. The "many" (crow's-foot) side carries a cardinality bar (Workbench style) by default — whether a parent may have zero children isn't expressible in standard DBML.

Optional collection (opt-in): if the foreign-key column's note contains the word optional, the crow's-foot side is drawn with a ring instead of the bar ("zero or many"):

Table line_items {
  order_id int [not null, ref: > orders.id]            // crow's foot + bar
  promo_id int [ref: > promos.id, note: 'optional']    // crow's foot + ring (zero or many)
}

<DbmlViewer> props

| Prop | Type | Default | Description | | ---------------- | ----------------------------- | ------- | ---------------------------------------------- | | dbml | string | — | DBML source to render. Parsed lazily (loads @dbml/core). Provide dbml or schema. | | schema | ParsedSchema | — | Pre-parsed schema; skips parsing so @dbml/core never enters your bundle. See Avoiding the parser bundle. | | fitView | boolean | true | Fit the diagram into view on load. | | showControls | boolean | true | Show the zoom/pan controls. | | showMiniMap | boolean | false | Show the minimap. | | showBackground | boolean | true | Show the dotted background grid. | | layoutOptions | LayoutOptions | — | Algorithm, direction, and node spacing (see below). | | edgeConnection | 'column' \| 'floating' | 'column' | How edges attach to tables (see Edge connection mode). | | onParseError | (error: DbmlParseError) => void | — | Called when the DBML fails to parse. | | onLayoutError | (error: LayoutError) => void | — | Called when a dagre/elk layout fails (e.g. missing optional dep). | | nodePositions | NodePositions | — | Saved table positions (id → {x,y}) to restore. See Persisting positions. | | onNodePositionsChange | (positions: NodePositions) => void | — | Called after a table drag with the full positions map to persist. | | className | string | — | Class applied to the wrapper element. | | style | CSSProperties | — | Inline style for the wrapper element. |

If the DBML is invalid, the viewer renders the parser errors inline (one line per problem, with Line:column — message) and, if provided, calls onParseError. The DbmlParseError also exposes a structured diagnostics: DbmlDiagnostic[] array ({ message, line?, column?, code? }) if you want to render errors your own way:

<DbmlViewer
  dbml={dbml}
  onParseError={(err) => err.diagnostics.forEach((d) => console.log(d.line, d.message))}
/>

Layout

layoutOptions.algorithm selects how tables are positioned:

| Algorithm | Dependency | Notes | | ---------- | ----------------- | --------------------------------------------------------------------- | | 'simple' | none (default) | Built-in left-to-right layering. Zero dependencies, synchronous. | | 'dagre' | @dagrejs/dagre | Sugiyama layered layout with crossing minimization. | | 'elk' | elkjs | ELK layered algorithm; strongest crossing reduction for dense schemas. |

dagre and elk are optional peer dependencies, loaded on demand only when selected — they are not in the default bundle. Install whichever you use:

npm install @dagrejs/dagre   # for algorithm: 'dagre'
npm install elkjs            # for algorithm: 'elk'

<DbmlViewer
  dbml={dbml}
  layoutOptions={{ algorithm: 'elk', direction: 'LR', horizontalGap: 120, verticalGap: 40 }}
  onLayoutError={(e) => console.error(e.message)}
/>

If a dagre/elk layout throws (e.g. the dependency isn't installed), the viewer falls back to the built-in simple layout and calls onLayoutError. direction is 'LR' (left→right) or 'TB' (top→bottom).

The simple layout places FK-connected tables as the layered graph, then packs tables with no relations into a grid below it (filling left-to-right, then wrapping) instead of stacking them in a tall left-hand column.

Node width

Table nodes are sized to their content (the widest column row and the header), clamped between minNodeWidth and maxNodeWidth. Content wider than maxNodeWidth is truncated with an ellipsis (the full text stays in the element's title). Both are part of layoutOptions:

| Option | Default | Notes | | -------------- | ------- | ------------------------------------------------------------------ | | minNodeWidth | 160 | Lower bound for a node's width, in px. | | maxNodeWidth | 320 | Upper bound; longer column names/types ellipsize at this width. |

<DbmlViewer dbml={dbml} layoutOptions={{ minNodeWidth: 200, maxNodeWidth: 480 }} />

Edge connection mode

edgeConnection controls how relations attach to tables:

| Value | Behaviour | | ------------ | ------------------------------------------------------------------------------------ | | 'column' | Default. Each edge anchors to its specific FK/PK column rows. | | 'floating' | Edges connect table-to-table, attaching wherever the two tables face each other and following them as they move (floating-edge style). |

<DbmlViewer dbml={dbml} edgeConnection="floating" />

Persisting node positions

Tables are draggable. To keep where the user moved them, store the positions yourself and pass them back via nodePositions. The library is storage-agnostic — onNodePositionsChange fires after each drag with the full id → {x, y} map:

const KEY = 'erd-positions';
const [positions, setPositions] = useState<NodePositions>(
  () => JSON.parse(localStorage.getItem(KEY) ?? '{}'),
);

const save = (next: NodePositions) => {
  setPositions(next);
  localStorage.setItem(KEY, JSON.stringify(next));
};

<DbmlViewer dbml={dbml} nodePositions={positions} onNodePositionsChange={save} />;

nodePositions is applied when the schema/layout (re)builds: a saved position wins, and tables without one fall back to auto-layout (so newly added tables still get placed). To reset to a fresh auto-layout, pass {} / undefined. The same precedence applies when switching layout algorithm — clear the saved map if you want the new algorithm to reposition everything.

Stable positions while editing

The viewer only re-runs auto-layout when the set of tables or the layout options change. Editing column-level details (columns, types, notes) — or even relations — between the existing tables keeps every node where it is and just refreshes the contents and edges. Adding a table keeps the existing tables in place and only positions the new one; changing the layout algorithm/direction reshuffles everything. This holds whether or not you use nodePositions, so manual drags survive ordinary edits.

To deliberately re-arrange everything, the control panel (when showControls is on) has an Auto layout button (hierarchy icon). Clicking it re-runs the current layout algorithm on all tables, fits the view, and — if you use nodePositions — emits the new arrangement via onNodePositionsChange so it persists.

Exporting to PNG / SVG

Pass a ref to get a DbmlViewerHandle and export the full diagram (all tables, framed at 100%) as an image. This uses the optional html-to-image dependency, loaded on demand:

npm install html-to-image

import { useRef } from 'react';
import { DbmlViewer, type DbmlViewerHandle } from 'dbml-erd-viewer';

function App() {
  const viewer = useRef<DbmlViewerHandle>(null);
  return (
    <>
      <button onClick={() => viewer.current?.download('schema.png', { type: 'png' })}>
        Export PNG
      </button>
      <DbmlViewer ref={viewer} dbml={dbml} />
    </>
  );
}

DbmlViewerHandle:

| Method | Description | | ------------------------------------------ | -------------------------------------------------- | | download(filename, options?) | Render the diagram and trigger a browser download. | | toDataUrl(options?) → Promise<string> | Return the image as a data URL. | | fitView(options?) | Fit the whole diagram into the viewport. | | zoomIn(options?) / zoomOut(options?) | Zoom by one step. | | zoomTo(level, options?) | Zoom to a specific level (1 = 100%). | | setCenter(x, y, options?) | Center the viewport on a flow-coordinate point. | | fitBounds(bounds, options?) | Fit a flow-coordinate rectangle into the viewport. | | setViewport(viewport, options?) / getViewport() | Set / read the viewport ({ x, y, zoom }). |

DiagramExportOptions: type ('png' | 'svg', default 'png'), padding (default 24), backgroundColor (defaults to the viewer's canvas color), pixelRatio (PNG sharpness, default 2). The export reflects the current theme. If html-to-image isn't installed, the methods reject with an ExportError.

The viewport methods delegate to the underlying React Flow instance (and are no-ops before the diagram mounts); their option types (FitViewOptions, Viewport, …) are re-exported from the package.

Lower-level API

The parsing and layout helpers are exported for building custom renderers:

import { parseDbml, layoutSchema } from 'dbml-erd-viewer';

const schema = await parseDbml(dbml); // async: loads @dbml/core on demand → { tables, relations }
const boxes = layoutSchema(schema); //   Map<tableId, { x, y, width, height }>

See src/types.ts for the full ParsedSchema, TableInfo, ColumnInfo, and RelationInfo shapes.

Avoiding the parser bundle

@dbml/core is large. To keep it out of your bundle entirely, parse the DBML outside the browser (server, build step, or a background worker) and pass the resulting ParsedSchema to the schema prop instead of dbml:

// server / build: import { parseDbml } from 'dbml-erd-viewer'; const schema = await parseDbml(src);
// client:
<DbmlViewer schema={schema} />

When schema is set the viewer never executes the import('@dbml/core'), so its chunk is never downloaded. Pass either dbml or schema (memoize schema so its reference is stable). With dbml, the parser is still loaded lazily as a separate chunk, so it never bloats your entry bundle either way. (@dbml/core is only needed for the dbml path — install it when you use it.)

Theming

There are three ways to customize the look, from most to least convenient:

1. The theme prop — pass a (partial) DbmlViewerTheme; each token maps to a CSS variable and only the keys you set are overridden. The darkTheme and lightTheme presets are exported:

import { DbmlViewer, darkTheme, type DbmlViewerTheme } from 'dbml-erd-viewer';

// Use a preset directly…
<DbmlViewer dbml={dbml} theme={darkTheme} />;

// …or spread a preset and tweak, or pass your own partial theme:
const custom: DbmlViewerTheme = { ...darkTheme, headerBackground: '#4f46e5', edge: '#818cf8' };
<DbmlViewer dbml={dbml} theme={custom} />;

Available tokens: canvas, background, border, headerBackground, headerForeground, rowForeground, typeForeground, rowHover, rowHighlight, primaryKey, foreignKey, edge, edgeActive, fontFamily.

2. CSS custom properties — the same variables, scoped to .dv-viewer, set in your own stylesheet for an app-wide default:

.dv-viewer {
  --dv-header-bg: #1e3a8a;
  --dv-edge: #1e3a8a;
  --dv-pk: #b7791f;
  --dv-fk: #2b6cb0;
}

3. Class hooks — for anything beyond colors/fonts, target the structural classes directly: .dv-table, .dv-table__header, .dv-row, .dv-row--highlighted, .dv-badge--pk, .dv-badge--fk, .dv-erd-edge__path, .dv-erd-marker. You can also pass className/style to the wrapper.

All bundled styles live in the dbml-erd-viewer cascade layer. Because unlayered styles always beat layered ones, your own CSS (options 2 and 3) overrides the defaults regardless of import order or selector specificity — no !important required.

Fonts

The table text uses the fontFamily theme token (CSS variable --dv-font), which defaults to the system UI font stack. To use your own font, set it via the theme prop or the CSS variable:

<DbmlViewer dbml={dbml} theme={{ fontFamily: '"Inter", sans-serif' }} />

/* app-wide, in your own stylesheet */
.dv-viewer { --dv-font: "Inter", sans-serif; }

The library does not bundle any fonts — load the font yourself (the same way you load fonts for the rest of your app), then reference it by name:

<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter&display=swap" />

/* or self-hosted */
@font-face { font-family: "Inter"; src: url("/fonts/Inter.woff2") format("woff2"); }

Image export: PNG/SVG export inlines the rendered text, so a custom font must be loaded before export or the image falls back to a default font. The viewer waits for document.fonts.ready before capturing, which covers fonts already requested by the page; if you load a font only for the diagram, trigger it first (e.g. await document.fonts.load('16px "Inter"')) before calling download() / toDataUrl().

Acknowledgements

This library is built on top of two excellent projects:

• @dbml/core (npm, docs) — the official DBML parser, used to parse the schema into tables and relations.
• @xyflow/react (npm, docs) — React Flow, used to render the interactive node-and-edge diagram.

Many thanks to their maintainers and contributors.

License

MIT