DLH.io ERD Viewer Deux

Popular ERD viewer designed by DLH.io originally to provide a better ERD experience to users of the DLH.io platform to visualize relationships in complicated data sources such as Salesforce.com, Dayforce, Paycor, and other operational systems.

Roadmap

Future features and enhancements are taken by reqeust and PR.

More about DLH.io

ETL/ELT, data integration, API solutions, and data engineering for reports, dashboards, and AI use cases. See more at DLH.io

@dlh.io/dlh-erd-viewer-deux

A React component for visualizing database Entity-Relationship Diagrams (ERD) from DBML and TBLS schema formats.

Installation

npm install @dlh.io/dlh-erd-viewer-deux

Quick Start

import { ERDViewer } from '@dlh.io/dlh-erd-viewer-deux';
import '@dlh.io/dlh-erd-viewer-deux/styles.css';

const dbmlSchema = `
Table users {
  id integer [pk]
  username varchar(255) [not null]
  email varchar(255) [not null]
}

Table posts {
  id integer [pk]
  title varchar(255) [not null]
  author_id integer [ref: > users.id]
}
`;

function App() {
  return (
    <div style={{ width: '100%', height: '600px' }}>
      <ERDViewer
        format="dbml"
        content={dbmlSchema}
      />
    </div>
  );
}

Props

Required Props

| Prop | Type | Description | |------|------|-------------| | format | 'dbml' \| 'tbls' | The schema format of the content | | content | string | The schema content to parse and display |

Optional Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | className | string | '' | Additional CSS class names for the container | | style | React.CSSProperties | - | Inline styles for the container | | positions | PositionMetadata | - | Pre-defined table positions for the layout | | devMode | boolean | false | Enable developer mode with position copying tools | | draggable | boolean | false | Allow users to drag and reposition tables | | showMinimap | boolean | true | Show or hide the minimap navigation | | showInfoPanel | boolean | true | Show or hide the information side panel | | displayMode | DisplayMode | 'all' | Column display mode: 'all', 'keys', or 'tableOnly' | | layoutAlgorithm | LayoutAlgorithm | 'default' | Layout algorithm for table positioning | | reverseAnimationFlow | boolean | false | Reverse the animation flow direction on connector lines | | tableOnlyConnectionMode | TableOnlyConnectionMode | 'center' | Connection mode when in table-only display | | toolbarAlignment | PanelAlignment | 'center' | Toolbar position: 'left', 'center', or 'right' | | infoPaneAlignment | PanelAlignment | 'right' | Info panel position: 'left' or 'right' | | printExportLogo | string | DLH logo | URL of logo to watermark on exports | | printExportLogoPosition | WatermarkPosition | 'top-left' | Position of watermark: 'top-left', 'top-right', 'bottom-left', 'bottom-right' | | theme | ERDViewerTheme | - | Theme overrides via CSS custom properties |

Callback Props

| Prop | Type | Description | |------|------|-------------| | onExport | (format: 'png' \| 'pdf') => void | Called when diagram is exported | | onPositionsChange | (positions: PositionMetadata) => void | Called when table positions change (in devMode or draggable) | | onTableSelect | (table: Table \| null) => void | Called when a table is selected | | onColumnSelect | (table: Table \| null, columnName: string \| null) => void | Called when a column is selected | | onDisplayModeChange | (mode: DisplayMode) => void | Called when display mode changes | | onLayoutAlgorithmChange | (algorithm: LayoutAlgorithm) => void | Called when layout algorithm changes |

Types

DisplayMode

Controls which columns are shown in table cards:

type DisplayMode = 'all' | 'keys' | 'tableOnly';

• 'all' - Show all columns
• 'keys' - Show only primary and foreign key columns
• 'tableOnly' - Show only table names (no columns)

LayoutAlgorithm

Controls how tables are automatically positioned:

type LayoutAlgorithm = 'default' | 'hierarchical' | 'force' | 'grid' | 'spiral' | 'proximity';

• 'default' - Dagre-based top-to-bottom layout
• 'hierarchical' - Left-to-right hierarchical layout
• 'force' - Force-directed layout
• 'grid' - Grid pattern layout
• 'spiral' - Spiral pattern layout
• 'proximity' - Groups related tables together

PanelAlignment

type PanelAlignment = 'left' | 'center' | 'right';

WatermarkPosition

type WatermarkPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';

PositionMetadata

Pre-defined positions for tables:

interface PositionMetadata {
  schemaFormat?: 'dbml' | 'tbls';
  capturedAt?: string;
  version?: string;
  positions: TablePosition[];
}

interface TablePosition {
  tableName: string;
  x: number;
  y: number;
}

CSS Customization

The component uses CSS custom properties (variables) for theming. You can override these in your application's CSS:

:root {
  /* Core colors */
  --erd-primary: #3b82f6;
  --erd-secondary: #64748b;
  --erd-background: #ffffff;
  --erd-surface: #f8fafc;
  --erd-border: #e2e8f0;
  --erd-text: #1e293b;
  --erd-text-muted: #64748b;
  --erd-highlight: #3b82f6;

  /* Key indicators */
  --erd-pk: #eab308;           /* Primary key color */
  --erd-fk: #8b5cf6;           /* Foreign key color */

  /* Typography */
  --erd-font-family: ui-sans-serif, system-ui, sans-serif;
  --erd-font-mono: ui-monospace, monospace;

  /* Toolbar */
  --erd-toolbar-text: #1e293b;

  /* Connector lines */
  --erd-edge-color: #64748b;
  --erd-edge-highlight-color: #3b82f6;
  --erd-animation-color: #3b82f6;

  /* Table cards */
  --erd-table-header-bg: #3b82f6;
  --erd-table-header-text: #ffffff;
  --erd-table-column-bg: #ffffff;
  --erd-table-column-highlight-bg: #eff6ff;

  /* Info panel */
  --erd-info-panel-bg: #ffffff;
  --erd-info-panel-header-bg: #f8fafc;
}

Using the theme prop

You can also pass theme overrides directly via the theme prop:

<ERDViewer
  format="dbml"
  content={schema}
  theme={{
    '--erd-primary': '#10b981',
    '--erd-highlight': '#10b981',
    '--erd-table-header-bg': '#10b981',
  }}
/>

Examples

Basic Usage

import { ERDViewer } from '@dlh.io/dlh-erd-viewer-deux';
import '@dlh.io/dlh-erd-viewer-deux/styles.css';

function BasicExample() {
  const schema = `
    Table users {
      id integer [pk]
      name varchar(255)
    }
  `;

  return (
    <div style={{ width: '100%', height: '500px' }}>
      <ERDViewer format="dbml" content={schema} />
    </div>
  );
}

With Custom Layout and Display Mode

function CustomLayoutExample() {
  return (
    <ERDViewer
      format="dbml"
      content={schema}
      layoutAlgorithm="hierarchical"
      displayMode="keys"
      toolbarAlignment="left"
    />
  );
}

With Selection Callbacks

function SelectionExample() {
  const handleTableSelect = (table) => {
    if (table) {
      console.log('Selected table:', table.name);
    }
  };

  const handleColumnSelect = (table, columnName) => {
    if (table && columnName) {
      console.log(`Selected column: ${table.name}.${columnName}`);
    }
  };

  return (
    <ERDViewer
      format="dbml"
      content={schema}
      onTableSelect={handleTableSelect}
      onColumnSelect={handleColumnSelect}
    />
  );
}

With Custom Export Watermark

function ExportExample() {
  return (
    <ERDViewer
      format="dbml"
      content={schema}
      printExportLogo="https://example.com/my-logo.png"
      printExportLogoPosition="bottom-right"
      onExport={(format) => console.log(`Exported as ${format}`)}
    />
  );
}

Developer Mode for Position Capture

Enable devMode to capture table positions for later use:

function DevModeExample() {
  const handlePositionsChange = (positions) => {
    // Save positions to use as the `positions` prop later
    console.log(JSON.stringify(positions, null, 2));
  };

  return (
    <ERDViewer
      format="dbml"
      content={schema}
      devMode={true}
      draggable={true}
      onPositionsChange={handlePositionsChange}
    />
  );
}

Using Pre-defined Positions

const savedPositions = {
  schemaFormat: 'dbml',
  positions: [
    { tableName: 'users', x: 100, y: 100 },
    { tableName: 'posts', x: 400, y: 100 },
    { tableName: 'comments', x: 400, y: 300 },
  ],
};

function PositionedExample() {
  return (
    <ERDViewer
      format="dbml"
      content={schema}
      positions={savedPositions}
    />
  );
}

Dark Theme Example

function DarkThemeExample() {
  return (
    <ERDViewer
      format="dbml"
      content={schema}
      theme={{
        '--erd-background': '#1e293b',
        '--erd-surface': '#334155',
        '--erd-border': '#475569',
        '--erd-text': '#f1f5f9',
        '--erd-text-muted': '#94a3b8',
        '--erd-table-header-bg': '#3b82f6',
        '--erd-table-column-bg': '#1e293b',
        '--erd-toolbar-text': '#f1f5f9',
      }}
    />
  );
}

Next.js Usage

For Next.js applications, use dynamic import with SSR disabled:

import dynamic from 'next/dynamic';

const ERDViewer = dynamic(
  () => import('@dlh.io/dlh-erd-viewer-deux').then((mod) => mod.ERDViewer),
  { ssr: false }
);

// Import CSS in your layout or page
import '@dlh.io/dlh-erd-viewer-deux/styles.css';

export default function Page() {
  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <ERDViewer format="dbml" content={schema} />
    </div>
  );
}

Supported Schema Formats

DBML

The component supports DBML (Database Markup Language) format:

Table users {
  id integer [pk, increment]
  username varchar(255) [not null, unique]
  email varchar(255) [not null]
  created_at timestamp [default: `now()`]
}

Table posts {
  id integer [pk, increment]
  title varchar(255) [not null]
  content text
  author_id integer [ref: > users.id]
}

TBLS

The component also supports TBLS JSON format for schema documentation.

License

MIT