Visualize JSONas InteractiveGraph Structures

1import { JsonGraph } from 'jsongraphs';
2 
3const graph = new JsonGraph(opts: JsonGraphOptions);

1// From a plain object
2await graph.load({ name: "Alice", age: 30 });
3 
4// From a JSON string
5await graph.load('{"hello": "world"}');
6 
7// From a file input
8const file = fileInput.files[0];
9await graph.load(file);
10 
11// From a URL (auto-fetches and streams)
12await graph.load(new URL('https://api.example.com/data.json'));
13 
14// From a fetch() stream (most memory-efficient for large files)
15const res = await fetch('/huge-data.json');
16await graph.load(res.body!);

1// Switch to radial layout
2graph.setLayout('radial');
3 
4// Switch back to tree layout
5graph.setLayout('tree');

1import { darkTheme, defaultTheme } from 'jsongraphs';
2 
3// Apply dark theme
4graph.setTheme(darkTheme);
5 
6// Apply light theme
7graph.setTheme(defaultTheme);
8 
9// Apply a custom theme
10graph.setTheme(myCustomTheme);

1// One-liner to toggle light ↔ dark
2graph.toggleTheme();

1graph.fitView();

1graph.zoomIn();   // scale × 1.15
2graph.zoomOut();  // scale × 0.87

1graph.expandAll();    // Show all nodes
2graph.collapseAll();  // Collapse all (keep root visible)

1graph.invalidateCache();

1// In a React useEffect cleanup
2return () => graph.destroy();
3 
4// Or manually when done
5graph.destroy();

1type JsonSource =
2  | File                       // Browser File API (e.g. from <input type="file">)
3  | ReadableStream<Uint8Array>  // WHATWG Streams (e.g. fetch().body)
4  | string                     // Raw JSON string
5  | URL                        // URL — fetched and streamed automatically
6  | object;                    // Any plain JS object / array

1type LayoutType = 'tree' | 'radial';

1type NodeType = 'object' | 'array' | 'string' | 'number' | 'boolean' | 'null';

1interface NodePosition {
2  x: number;
3  y: number;
4  vx: number;  // velocity used by force layout
5  vy: number;
6}
7 
8interface GraphNode {
9  id: string;
10  type: NodeType;
11  key?: string;
12  value?: string;
13  childCount: number;
14  depth: number;
15  parentId?: string;
16  expanded: boolean;
17  pos: NodePosition;
18  width: number;
19  height: number;
20  highlighted: boolean;
21  hovered: boolean;
22  alpha: number;
23  transparent?: boolean;
24}

1interface GraphEdge {
2  id: string;
3  sourceId: string;
4  targetId: string;
5  label?: string;    // JSON key that connects these nodes
6  caption?: string;  // Optional pill label at edge midpoint
7  alpha: number;     // Fade-in animation progress
8}

1interface ParseOptions {
2  maxDepth?: number;  // Max nesting depth. Default: 200
3  maxNodes?: number;  // Max total nodes. Default: 500_000
4  chunkSize?: number; // Text decoder chunk in bytes. Default: 65_536 (64 KB)
5}

1import { ParseLimitError } from 'jsongraphs';
2 
3class ParseLimitError extends Error {
4  readonly kind: 'depth' | 'nodes';
5}
6 
7// Usage
8const graph = new JsonGraph({
9  container,
10  maxNodes: 10_000,
11  onError: (err) => {
12    if (err instanceof ParseLimitError) {
13      if (err.kind === 'nodes') {
14        console.warn('Too many nodes! Increase maxNodes.');
15      } else if (err.kind === 'depth') {
16        console.warn('JSON too deeply nested! Increase maxDepth.');
17      }
18    }
19  },
20});

1interface NodeColors {
2  fill:   string;  // Node background
3  stroke: string;  // Node border
4  text:   string;  // Node label text
5  badge:  string;  // Type badge colour
6}
7 
8interface Theme {
9  name:       string;
10  background: string;  // Canvas background colour
11  gridLine:   string;  // Subtle grid line colour
12 
13  nodeColors: Record<NodeType, NodeColors>;  // Per-type colours
14 
15  edge: {
16    stroke:        string;  // Default edge colour
17    highlight:     string;  // Highlighted edge colour
18    width:         number;  // Edge line width in px
19    captionBg:     string;  // Caption pill background
20    captionText:   string;  // Caption pill text
21    captionBorder: string;  // Caption pill border
22  };
23 
24  font: {
25    family:    string;  // CSS font-family
26    keySize:   number;  // Key label font size
27    valueSize: number;  // Value label font size
28    typeSize:  number;  // Type badge font size
29  };
30 
31  node: {
32    radius:       number;  // Corner radius
33    paddingX:     number;  // Horizontal padding
34    paddingY:     number;  // Vertical padding
35    minWidth:     number;  // Minimum node width
36    shadowBlur:   number;  // Drop shadow blur radius
37    shadowColor:  string;  // Drop shadow colour
38    shadowOffset: number;  // Drop shadow offset
39  };
40 
41  ui: {
42    panelBg:          string;  // Toolbar / search / minimap background
43    panelBorder:      string;  // Panel border colour
44    panelShadow:      string;  // Panel box-shadow CSS value
45    btnHover:         string;  // Button hover background
46    btnActive:        string;  // Button active / selected background
47    text:             string;  // Primary UI text colour
48    textMuted:        string;  // Secondary UI text colour
49    inputBg:          string;  // Search input background
50    inputText:        string;  // Search input text colour
51    inputPlaceholder: string;  // Search placeholder colour
52    focusRing:        string;  // Focus ring colour
53    separator:        string;  // Separator line colour
54    minimapViewport:  string;  // Minimap viewport rect stroke
55  };
56}

1import { defaultTheme, darkTheme } from 'jsongraphs';
2 
3// Apply light theme
4graph.setTheme(defaultTheme);
5 
6// Apply dark theme
7graph.setTheme(darkTheme);
8 
9// Toggle between them
10graph.toggleTheme();

1import { defaultTheme, type Theme } from 'jsongraphs';
2 
3const sunsetTheme: Theme = {
4  ...defaultTheme,
5  name: 'sunset',
6  background: '#1a0a00',
7  gridLine: 'rgba(255,120,50,0.05)',
8 
9  nodeColors: {
10    object:  { fill: '#2a1000', stroke: '#ff6820', text: '#ffd0a0', badge: '#ff6820' },
11    array:   { fill: '#001a10', stroke: '#20d080', text: '#a0ffc8', badge: '#20d080' },
12    string:  { fill: '#00101a', stroke: '#20a0ff', text: '#a0d8ff', badge: '#20a0ff' },
13    number:  { fill: '#1a1000', stroke: '#c0b020', text: '#ffe890', badge: '#c0b020' },
14    boolean: { fill: '#1a0020', stroke: '#c040c0', text: '#f0a0f0', badge: '#c040c0' },
15    null:    { fill: '#151510', stroke: '#808070', text: '#c8c8b0', badge: '#808070' },
16  },
17 
18  edge: {
19    ...defaultTheme.edge,
20    stroke: 'rgba(255,120,50,0.4)',
21    highlight: '#ff6820',
22  },
23 
24  ui: {
25    ...defaultTheme.ui,
26    panelBg: 'rgba(26,10,0,0.92)',
27    text: '#ffd0a0',
28    focusRing: '#ff6820',
29  },
30};
31 
32graph.setTheme(sunsetTheme);

1{
2  "user": {
3    "__CAPTION__": "is assigned to",
4    "name": "Alice",
5    "role": "admin"
6  },
7  "project": {
8    "__CAPTION__": "Project Details",
9    "title": "JsonGraphs Docs",
10    "status": "active"
11  }
12}

1// Stream directly from fetch — renders as data arrives
2const response = await fetch('/api/huge-dataset.json');
3await graph.load(response.body!);
4 
5// From a File input (also streamed)
6document.querySelector('input[type="file"]')
7  .addEventListener('change', async (e) => {
8    const file = e.target.files[0];
9    await graph.load(file);  // Streams the file, no full read into memory
10  });
11 
12// With limit guards
13const graph = new JsonGraph({
14  container,
15  maxNodes: 50_000,   // Stop at 50k nodes
16  maxDepth: 100,      // Stop at depth 100
17  onError: (err) => {
18    console.error('Limit reached:', err.message);
19  },
20});