Custom Diagrams

Build architecture diagrams, system designs, and process flows with full control over nodes and edges.

Open Live Example: System Architecture Diagram

Example

{
  "nodes": [
    {
      "id": "client",
      "label": "Mobile App",
      "imageUrl": "https://cdn-icons-png.flaticon.com/512/149/149071.png",
      "platform": "iOS/Android",
      "version": "2.1.0"
    },
    {
      "id": "api-gateway",
      "label": "API Gateway",
      "port": 443,
      "protocol": "HTTPS",
      "requests_per_sec": 1500
    },
    {
      "id": "backend",
      "label": "Backend Services",
      "nodes": [
        {
          "id": "auth-service",
          "label": "Auth Service",
          "status": "healthy",
          "uptime": 99.9
        },
        {
          "id": "data-service",
          "label": "Data Service",
          "instances": 3,
          "load_balanced": true
        }
      ]
    },
    {
      "id": "database",
      "label": "PostgreSQL",
      "imageUrl": "https://cdn-icons-png.flaticon.com/512/5968/5968342.png",
      "size": "500GB",
      "replicas": 2
    }
  ],
  "edges": [
    { "from": "client", "to": "api-gateway", "label": "HTTPS Request" },
    { "from": "api-gateway", "to": "auth-service", "label": "Authenticate" },
    { "from": "api-gateway", "to": "data-service", "label": "Fetch Data" },
    { "from": "auth-service", "to": "database", "label": "Verify User" },
    { "from": "data-service", "to": "database", "label": "Query" }
  ]
}

You can add a custom_theme field to any node to fully customize its appearance using a custom theme. This allows you to override default styles, colors, and more for individual nodes or groups. See the Custom Theme Guide for details and examples.

Example:

{
  "id": "api-gateway",
  "label": "API Gateway",
  "custom_theme": {
    "NODE": {
      "NODE": "#1e293b",
    },
    "EDGE": {
      "EDGE": "#38bdf8",
      "LABEL": "#fff"
    },
    "TEXT": {
      "TEXT": "#fff"
    }
  }
}

Icons

You can use any of the 200,000+ icons available on iconify.design for imageUrl or iconUrl. The format is set:icon-name, for example fa:user or fa:desktop. Use valid Iconify names; invalid names will not render.

{
  "id": "server",
  "label": "Web Server",
  "imageUrl": "fa:desktop"
}

Structure

Nodes

Every node must have an id field. Beyond that, you can include any primitive key-value pairs.

Prop

Type

Custom Fields Example:

{
  "id": "server",
  "label": "API Server",
  "iconUrl": "fa:server",
  "port": 3000,
  "status": "active",
  "uptime": 99.9,
  "ssl": true
}

Edges

Edges define connections between nodes.

Prop

Type

Configuration

You can include an optional configuration object at the root level to customize field mappings. This is useful when your data has field names that conflict with the defaults (e.g., a column named id or label).

Schema Field Mappings

The configuration.schema object lets you override which fields are used for node IDs, labels, edges, etc.

{
  "configuration": {
    "schema": {
      "keys": {
        "nodes": "nodes",
        "edges": "edges",
        "direction": "direction"
      },
      "node": {
        "id": "id",
        "label": "label",
        "imageUrl": "imageUrl",
        "iconUrl": "iconUrl",
        "customTheme": "custom_theme"
      },
      "edge": {
        "from": "from",
        "to": "to",
        "label": "label"
      }
    }
  },
  "nodes": [...],
  "edges": [...]
}

Example: Custom ID Field

If your data uses name as the unique identifier instead of id:

{
  "configuration": {
    "schema": {
      "node": { "id": "name" }
    }
  },
  "nodes": [
    { "name": "server-1", "status": "running" },
    { "name": "server-2", "status": "stopped" }
  ],
  "edges": [
    { "from": "server-1", "to": "server-2" }
  ]
}

Example: Database Schema Diagram

When visualizing database tables, column names like id or label may conflict with the diagram schema. Use a reserved field name like _table:

{
  "configuration": {
    "schema": {
      "node": { "id": "_table", "label": "_table" }
    }
  },
  "nodes": [
    {
      "_table": "users",
      "iconUrl": "logos:postgresql",
      "id": "🔑 uuid",
      "email": "varchar *",
      "name": "varchar"
    },
    {
      "_table": "posts",
      "iconUrl": "logos:postgresql",
      "id": "🔑 uuid",
      "user_id": "🔗 uuid",
      "title": "varchar *"
    }
  ],
  "edges": [
    { "from": "posts", "to": "users", "label": "user_id" }
  ]
}