Graph Renderer Component

The GraphRenderer component is an interactive, force-directed graph visualization built on top of D3.js force simulation. It supports hierarchical node structures, dynamic expansion/collapse, zoom controls, anchor links, and dark mode.

NodeRenderer: Title Display Examples

The NodeRenderer class handles all node rendering, including sophisticated title display with automatic truncation and ellipsis handling. Below are examples showcasing how titles are rendered at different lengths and zoom levels.

Short Titles (≤20 characters)

Short titles are displayed in full without truncation:

Loading demo...

Medium Titles (21-40 characters)

Medium titles may be truncated or wrapped across multiple lines:

Loading demo...

Long Titles (>40 characters)

Long titles are truncated to ensure at least 20 characters are shown before the ellipsis:

Loading demo...

Zoom Level Effects

The same title at different zoom levels. Notice how the text scales reactively while maintaining the 20-character minimum before ellipsis:

Short Title at Different Zoom Levels

Loading demo...

Medium Title at Different Zoom Levels

Loading demo...

Long Title at Different Zoom Levels

Loading demo...

Parent vs Leaf Nodes

Parent nodes (with children) are larger and show expansion arrows, while leaf nodes are smaller and show a leaf emoji:

Loading demo...

Key Features Demonstrated

20-Character Minimum: When ellipsis is shown, at least 20 characters of text are displayed before it
Reactive Scaling: Text scales with zoom level while staying within node boundaries
Multi-line Support: Long titles are distributed across up to 3 lines
Canvas Clipping: Text never protrudes outside the circular node shape
Smart Truncation: Ellipsis only appears when necessary, never alone

Features

Hierarchical Nodes: Support for nested node structures with expand/collapse functionality
Interactive Navigation: Click to expand/collapse, zoom with mouse wheel, pan by dragging
Anchor Links: Deep linking to specific nodes via URL hashes
Node Highlighting: Visual highlighting with golden glow for selected nodes
Smart Title Display: Automatic text truncation (20 chars) with ellipsis, distributed across 3 lines
Dark Mode Support: Automatically adapts to Docusaurus theme
Context Menu: Right-click nodes/edges to copy anchor links
Side Panel: View node/edge details on hover or click
Edge Labels: Display labels on graph edges
Status Indicators: Visual indicators for leaf nodes (🌿) and expandable nodes (▶/▼)
Zoom Limits: Intelligent zoom constraints to prevent over-zooming

Basic Usage

Simple Graph

A basic graph with two nodes and a link:

Loading graph...

<GraphRenderer data={{
  nodes: [
    { id: '1', label: 'Node A', title: 'Node A Title' },
    { id: '2', label: 'Node B', title: 'Node B Title' }
  ],
  links: [
    { source: '1', target: '2' }
  ]
}} />

Component API

Props

Prop	Type	Default	Description
`data`	`GraphData`	required	Graph data containing nodes and links
`width`	`number`	`800`	Graph width in pixels
`height`	`number`	`600`	Graph height in pixels
`graphId`	`string`	`'graph'`	Unique ID for anchor link support
`highlightNodeId`	`string`	`undefined`	Node ID to highlight programmatically
`highlightEdgeId`	`string`	`undefined`	Edge ID to highlight programmatically

Data Structure

Node

interface Node {
  id: string;              // Unique identifier (required)
  label: string;           // Display label (required)
  title?: string;          // Title text (displayed in node, max 20 chars)
  description?: string;    // Description (shown in side panel)
  color?: string;          // Node color (hex format)
  group?: number;          // Group number (for color assignment)
  children?: Node[];       // Child nodes (for hierarchical structure)
}

Link

interface Link {
  source: string;          // Source node ID (required)
  target: string;          // Target node ID (required)
  value?: number;          // Link weight (affects thickness)
  label?: string;          // Edge label text
  id?: string;             // Unique edge ID (for highlighting)
}

Feature Examples

Hierarchical Nodes with Expand/Collapse

Nodes can have children that are hidden by default. Click on a parent node to expand and reveal its children. Click again to collapse.

Visual Indicators:

Parent nodes (with children): Larger size (12px radius), show ▶ when collapsed, ▼ when expanded
Leaf nodes (no children): Smaller size (8px radius), show 🌿 emoji

Loading graph...

Try it:

Click on "Root" to expand and see Level 1 nodes
Click on "Level 1-A" to expand and see Level 2 nodes
Click on "Level 2-A1" to expand and see Level 3 nodes
Click again on any expanded node to collapse it

Title Display

Node titles are automatically:

Truncated to 20 characters with ellipsis (...) if longer
Distributed across up to 3 lines within the node
Scaled reactively with zoom level to always fit within node boundaries
Never protrude outside the circular node shape

Examples:

Short title: "Root Node" → displayed as-is
Medium title: "First Level Node A" → displayed as-is (18 chars)
Long title: "First Level Node C (No Children)" → truncated to "First Level Node ..." (20 chars)

Anchor Links and Node Highlighting

Create deep links to specific nodes using URL hashes. When a link is clicked, the graph will:

Automatically expand all parent nodes to make the target visible
Highlight the target node with a golden glow and border
Center and zoom the view on the highlighted node
Update the URL hash for shareable links

Link Format: #graphId-node-{nodeId}

Example Links:

Links to graph nodes are created dynamically when the graph is rendered
Use the highlightNodeId prop to highlight specific nodes programmatically

// In your MDX file, use the highlightNodeId prop:
<GraphRenderer 
  graphId="my-graph"
  highlightNodeId="level2-a1"

// Or programmatically:
<GraphRenderer 
  graphId="my-graph"
  highlightNodeId="level2-a1"
  data={...}
/>

Edge Labels

Edges can have labels displayed at their midpoint:

Loading graph...

links: [
  { 
    source: 'a', 
    target: 'b', 
    label: 'connects to',
    id: 'link-ab'  // Optional: for highlighting
  }
]

Custom Colors

Assign custom colors to nodes:

Loading graph...

If no color is specified, nodes use a default Neo4j-inspired color palette.

Node Descriptions

Add descriptions that appear in the side panel when hovering or clicking a node:

nodes: [
  { 
    id: '1', 
    label: 'Node A', 
    title: 'Node A Title',
    description: 'This is a detailed description that appears in the side panel when you hover or click on the node.'
  }
]

Interactive Controls

The graph includes a menu bar with the following controls:

Center: Centers the view on all visible nodes
Expand All: Expands all nodes with children
Collapse All: Collapses all expanded nodes
Hide/Show Pane: Toggles the side panel visibility

Mouse Interactions

Left Click Node:
- If node has children: Toggle expand/collapse
- Always: Select node and show details in side panel
Right Click Node/Edge: Open context menu to copy anchor link
Mouse Wheel: Zoom in/out (with intelligent limits)
Drag: Pan the graph view
Hover Node: Show node details in side panel

Zoom Behavior

The graph enforces intelligent zoom limits:

Zoom Out Limit: Prevents zooming out so far that the graph becomes less than 25% of viewport
Zoom In Limit: Prevents zooming in so far that a single node takes up more than 90% of viewport
Reactive Text: Text scales appropriately with zoom level while staying within node boundaries

Advanced Example

Here's a comprehensive example showcasing multiple features:

Loading graph...

Try these features:

Expand nodes: Click on nodes with ▶ to expand
Use highlightNodeId prop: Set highlightNodeId="level2-a1" to highlight specific nodes
Right-click: Right-click any node to copy its anchor link
Zoom: Use mouse wheel to zoom in/out
Pan: Click and drag to move the graph
View details: Hover or click nodes to see details in the side panel

Technical Details

Title Display Logic

The component implements sophisticated text rendering:

Character Limit: Titles are truncated to exactly 20 characters (17 chars + ... if longer)
Line Distribution: Text is distributed across up to 3 lines within the node
Word Breaking: Attempts to break at word boundaries when possible
Ellipsis Handling: Ellipsis always appears at the end, never alone
Reactive Scaling: Font size adjusts with zoom level to maintain readability
Boundary Enforcement: Canvas clipping ensures text never protrudes outside node circle
Width Constraints: Text width accounts for circular node shape (narrower at top/bottom)

Node Sizing

Parent nodes (with children): 12px radius
Leaf nodes (no children): 8px radius

Color Palette

Default colors (Neo4j-inspired):

#68BDF6 - Neo4j blue
#60BE86 - Green
#FF6B6B - Red
#FFD93D - Yellow
#A78BFA - Purple
#FB7185 - Pink
#34D399 - Emerald
#FBBF24 - Amber

Best Practices

Use unique graphId: When using multiple graphs on the same page, give each a unique graphId
Keep titles concise: Titles are limited to 20 characters; use descriptions for longer text
Provide descriptions: Add descriptions to nodes for better context in the side panel
Use anchor links: Create shareable links to specific nodes using the anchor link format
Organize hierarchically: Use the children property to create logical node hierarchies
Customize colors: Use the color property to create visual groupings

Troubleshooting

Text not displaying

Check that nodes have a title or label property
Verify the title is not empty after trimming

Nodes not expanding

Ensure parent nodes have a children array with at least one child
Check that child nodes have unique id values

Anchor links not working

Verify the graphId prop matches the hash format: #graphId-node-{nodeId}
Ensure the target node exists in the graph data
Check that parent nodes are being expanded correctly

Zoom not working

The graph enforces zoom limits; try zooming in smaller increments
Check browser console for any errors

NodeRenderer: Title Display Examples​

Short Titles (≤20 characters)​

Medium Titles (21-40 characters)​

Long Titles (>40 characters)​

Zoom Level Effects​

Short Title at Different Zoom Levels​

Medium Title at Different Zoom Levels​

Long Title at Different Zoom Levels​

Parent vs Leaf Nodes​

Key Features Demonstrated​

Features​

Basic Usage​

Simple Graph​

Component API​

Props​

Data Structure​

Node​

Link​

Feature Examples​

Hierarchical Nodes with Expand/Collapse​

Title Display​

Anchor Links and Node Highlighting​

Edge Labels​

Custom Colors​

Node Descriptions​

Interactive Controls​

Menu Bar​

Mouse Interactions​

Zoom Behavior​

Advanced Example​

Technical Details​

Title Display Logic​

Node Sizing​

Color Palette​

Best Practices​

Troubleshooting​

Text not displaying​

Nodes not expanding​

Anchor links not working​

Zoom not working​

NodeRenderer: Title Display Examples

Short Titles (≤20 characters)

Medium Titles (21-40 characters)

Long Titles (>40 characters)

Zoom Level Effects

Short Title at Different Zoom Levels

Medium Title at Different Zoom Levels

Long Title at Different Zoom Levels

Parent vs Leaf Nodes

Key Features Demonstrated

Features

Basic Usage

Simple Graph

Component API

Props

Data Structure

Node

Link

Feature Examples

Hierarchical Nodes with Expand/Collapse

Title Display

Anchor Links and Node Highlighting

Edge Labels

Custom Colors

Node Descriptions

Interactive Controls

Menu Bar

Mouse Interactions

Zoom Behavior

Advanced Example

Technical Details

Title Display Logic

Node Sizing

Color Palette

Best Practices

Troubleshooting

Text not displaying

Nodes not expanding

Anchor links not working

Zoom not working