NVL (Neo4j Visualization Library)

When to Use

Use this skill when building graph visualizations with NVL. Covers rendering setup, styling nodes and relationships, layout algorithms, user interaction handling, and proven patterns from production FinSight usage.

---

1. Installation & Packages

npm install @neo4j-nvl/base @neo4j-nvl/react @neo4j-nvl/interaction-handlers

Package	Purpose
@neo4j-nvl/base	Core NVL class, types (Node, Relationship, NvlOptions)
@neo4j-nvl/react	BasicNvlWrapper, InteractiveNvlWrapper, StaticPictureWrapper
@neo4j-nvl/interaction-handlers	ZoomInteraction, PanInteraction, ClickInteraction, etc.

---

2. React Wrappers

All wrappers accept a ref for imperative access to the underlying NVL instance.

import type NVL from "@neo4j-nvl/base";
const nvlRef = useRef<NVL>(null);
// Then: nvlRef.current.setZoom(1.5)

BasicNvlWrapper

Minimal wrapper — renders the graph, syncs prop changes, no built-in interaction handlers.

import { BasicNvlWrapper } from "@neo4j-nvl/react";

<BasicNvlWrapper
  ref={nvlRef}
  nodes={nodes}
  rels={relationships}
  layout="forceDirected"
  layoutOptions={{ enableCytoscape: true }}
  nvlOptions={{ initialZoom: 1 }}
  nvlCallbacks={{ onLayoutDone: () => console.log("done") }}
  zoom={0.8}
  pan={{ x: 0, y: 0 }}
  positions={nodePositions} // Apply positions via setNodePositions
  onInitializationError={(err) => {}}
  onClick={(event) => {}} // Native DOM events passed as props
/>;

InteractiveNvlWrapper (primary choice)

Full mouse event support — click, drag, hover, zoom, pan, box select, lasso.

import { InteractiveNvlWrapper } from "@neo4j-nvl/react";

<InteractiveNvlWrapper
  ref={nvlRef}
  nodes={nodes}
  rels={relationships}
  layout="forceDirected"
  layoutOptions={layoutOptions}
  nvlOptions={nvlOptions}
  nvlCallbacks={callbacks}
  zoom={0.8}
  pan={{ x: 0, y: 0 }}
  mouseEventCallbacks={{
    onNodeClick: (node, hitTargets, evt) => {},
    onNodeDoubleClick: (node, hitTargets, evt) => {},
    onNodeRightClick: (node, hitTargets, evt) => {},
    onRelationshipClick: (rel, hitTargets, evt) => {},
    onRelationshipDoubleClick: (rel, hitTargets, evt) => {},
    onRelationshipRightClick: (rel, hitTargets, evt) => {},
    onCanvasClick: (evt) => {},
    onCanvasDoubleClick: (evt) => {},
    onCanvasRightClick: (evt) => {},
    onHover: (element, hitTargets, evt) => {},
    onDrag: (nodes) => {},
    onPan: (evt) => {},
    onZoom: (zoomLevel) => {},
    onBoxSelect: ({ nodes, rels }) => {},
    onLassoSelect: ({ nodes, rels }) => {},
  }}
  interactionOptions={{}} // Toggle interaction behaviors
  onInitializationError={(err) => {}}
/>;

StaticPictureWrapper

Non-interactive render — for thumbnails, exports, or read-only views. Same props as BasicNvlWrapper minus interaction-related ones.

---

3. Node Interface

interface Node {
  // Required
  id: string; // Unique across all nodes AND relationships

  // Visual
  color?: string; // Background color
  size?: number; // Node dimensions
  icon?: string; // URL or data URI (must be square, must be black)
  overlayIcon?: { url: string; position?: number[]; size?: number };

  // Captions
  caption?: string; // Simple text label
  captions?: StyledCaption[]; // Multiple styled captions (overrides caption)
  captionSize?: number;
  captionAlign?: "center" | "top" | "bottom";

  // State
  selected?: boolean; // Blue border highlight
  hovered?: boolean; // Hover visual state
  activated?: boolean; // Activation state
  disabled?: boolean; // Grayed out
  pinned?: boolean; // Immune to layout forces

  // Experimental
  html?: HTMLElement; // DOM element rendered on top of node
}

type StyledCaption = {
  key?: string;
  value?: string;
  styles?: string[]; // e.g. ['bold', 'italic']
};

FinSight node mapping pattern

// Label-based style config → NVL node
const nvlNodes: NVLNode[] = visibleNodes.map((node) => {
  const primaryLabel = getPrimaryLabel(node); // node.labels[0]
  const styleConfig = getNodeStyleConfig(primaryLabel); // { baseColor, baseSize, icon }
  const displayName = getNodeDisplayName(node); // Label-aware formatting
  const iconDataUri = getCachedIconDataUri(iconName, "#000000"); // Black SVG data URI

  return {
    id: node.id,
    caption: displayName,
    captionAlign: "top",
    size: styleConfig.baseSize,
    color: styleConfig.baseColor,
    icon: iconDataUri,
    disabled: hiddenNodeIds.has(node.id),
    selected: selectedNodeIds.has(node.id),
    hovered: highlightedNodeIds.has(node.id),
  };
});

---

4. Relationship Interface

interface Relationship {
  // Required
  id: string; // Unique across all nodes AND relationships
  from: string; // Source node ID
  to: string; // Target node ID

  // Visual
  color?: string;
  width?: number;
  type?: string; // Relationship type label

  // Captions
  caption?: string;
  captions?: StyledCaption[]; // Overrides caption when set
  captionSize?: number;
  captionAlign?: "center" | "top" | "bottom";
  captionHtml?: HTMLElement; // Experimental

  // State
  selected?: boolean;
  hovered?: boolean;
  disabled?: boolean;

  // Overlay
  overlayIcon?: { url: string; position?: number[]; size?: number };
}

FinSight relationship mapping pattern

const nvlRelationships: NVLRelationship[] = visibleRelationships.map((rel) => {
  const styleConfig = getRelationshipStyleConfig(rel.type); // { color, width }
  return {
    id: rel.id,
    from: rel.source,
    to: rel.target,
    caption: rel.type,
    type: rel.type,
    width: styleConfig.width,
    color: styleConfig.color,
    disabled: hiddenNodeIds.has(rel.source) || hiddenNodeIds.has(rel.target),
    hovered:
      highlightedNodeIds.has(rel.source) || highlightedNodeIds.has(rel.target),
  };
});

---

5. NvlOptions

interface NvlOptions {
  // Zoom & Pan
  initialZoom?: number;
  minZoom?: number; // Default: 0.075
  maxZoom?: number; // Default: 10
  allowDynamicMinZoom?: boolean; // Default: true — exceed minZoom if content doesn't fit
  panX?: number;
  panY?: number;

  // Rendering
  renderer?: "webgl" | "canvas"; // Default: 'webgl'
  disableWebWorkers?: boolean; // Use synchronous layout fallback
  minimapContainer?: HTMLElement; // DOM element for minimap rendering

  // Layout
  layout?: Layout;
  layoutOptions?: LayoutOptions;

  // Instance
  instanceId?: string;
  callbacks?: ExternalCallbacks;

  // Accessibility & Telemetry
  disableAria?: boolean; // Default: false
  disableTelemetry?: boolean; // Default: false

  // Styling defaults
  styling?: {
    defaultNodeColor?: string;
    defaultRelationshipColor?: string;
    disabledItemColor?: string;
    disabledItemFontColor?: string;
    selectedBorderColor?: string;
    selectedInnerBorderColor?: string;
    dropShadowColor?: string;
    nodeDefaultBorderColor?: string;
    minimapViewportBoxColor?: string;
    iconStyle?: { scale?: number }; // e.g. 0.6 = 60% of node size
  };
}

FinSight options pattern

const nvlOptions = useMemo(
  () => ({
    disableWebWorkers: true,
    renderer: "canvas" as const,
    minimapContainer: minimapElement || undefined,
    styling: {
      minimapViewportBoxColor: "#3B82F6",
      iconStyle: { scale: 0.6 },
    },
  }),
  [minimapElement],
);

---

6. Layout Configuration

type Layout = "forceDirected" | "hierarchical" | "d3Force" | "grid" | "free";

forceDirected (default)

interface ForceDirectedOptions {
  enableCytoscape?: boolean; // CoseBilkent for smaller graphs — better initial positioning
  enableVerlet?: boolean; // New physics engine (default: true)
  intelWorkaround?: boolean; // Fixes Intel GPU WebGL shader issues
}

hierarchical

interface HierarchicalOptions {
  direction?: "left" | "right" | "up" | "down";
  packing?: "bin" | "stack";
}

Changing layouts at runtime

// Via ref — use setTimeout to avoid race conditions with NVL initialization
useEffect(() => {
  const timer = setTimeout(() => {
    nvlRef.current?.setLayout(layout);
  }, 50);
  return () => clearTimeout(timer);
}, [layout]);

// Update layout options without changing algorithm
nvlRef.current.setLayoutOptions({ direction: "up" });

// Check if layout is still animating
nvlRef.current.isLayoutMoving(); // boolean

---

7. Interaction Handlers

Used with BasicNvlWrapper (or vanilla JS) when you need manual control. InteractiveNvlWrapper handles these internally via mouseEventCallbacks.

import {
  ZoomInteraction,
  PanInteraction,
  ClickInteraction,
  DragNodeInteraction,
  HoverInteraction,
  BoxSelectInteraction,
  LassoInteraction,
} from "@neo4j-nvl/interaction-handlers";

Registering handlers (via ref)

// Must wait for NVL initialization — use setTimeout
useEffect(() => {
  const timer = setTimeout(() => {
    if (nvlRef.current) {
      new ZoomInteraction(nvlRef.current);
      new PanInteraction(nvlRef.current);
    }
  });
  return () => clearTimeout(timer);
}, []);

Handler classes and callbacks

Handler	Constructor	Callback	Signature
ZoomInteraction	new ZoomInteraction(nvl)	onZoom	(zoomLevel: number) => void
PanInteraction	new PanInteraction(nvl)	onPan	(panning: any) => void
ClickInteraction	new ClickInteraction(nvl)	onNodeClick, onNodeDoubleClick, onNodeRightClick, onRelationshipClick, onRelationshipDoubleClick, onRelationshipRightClick, onSceneClick	Various
DragNodeInteraction	new DragNodeInteraction(nvl)	onDrag	(nodes: Node[]) => void
HoverInteraction	new HoverInteraction(nvl)	onHover	(element, hitTargets, event) => void
BoxSelectInteraction	new BoxSelectInteraction(nvl)	onBoxSelect	({ nodes, rels }) => void
LassoInteraction	new LassoInteraction(nvl)	onLassoSelect	({ nodes, rels }) => void

// Update callback after construction
handler.updateCallback("onNodeClick", (node: Node) => {
  console.log("clicked", node);
});

---

8. NVL Instance Methods (via ref)

Graph Manipulation

// Add elements
nvl.addElementsToGraph(nodes: Node[], relationships: Relationship[]): void

// Add new + update existing (matches by ID)
nvl.addAndUpdateElementsInGraph(nodes?: Node[] | PartialNode[], rels?: Relationship[] | PartialRelationship[]): void

// Update properties on existing elements only
nvl.updateElementsInGraph(nodes: Node[] | PartialNode[], rels: Relationship[] | PartialRelationship[]): void

// Remove by ID (removes adjacent relationships too)
nvl.removeNodesWithIds(nodeIds: string[]): void
nvl.removeRelationshipsWithIds(relIds: string[]): void

Data Retrieval

nvl.getNodes(): Node[]
nvl.getNodeById(id: string): Node
nvl.getRelationships(): Relationship[]
nvl.getRelationshipById(id: string): Relationship
nvl.getNodePositions(): (Node & Point)[]
nvl.getPositionById(id: string): Node
nvl.getNodesOnScreen(): { nodes: Node[]; rels: Relationship[] }

Viewport

nvl.setZoom(zoomValue: number): void
nvl.resetZoom(): void                     // Resets to 0.75
nvl.getScale(): number
nvl.setPan(panX: number, panY: number): void
nvl.getPan(): Point                        // { x, y }
nvl.setZoomAndPan(zoom: number, panX: number, panY: number): void
nvl.fit(nodeIds: string[], zoomOptions?: ZoomOptions): void

type ZoomOptions = {
  animated?: boolean;
  maxZoom?: number;
  minZoom?: number;
  noPan?: boolean; // Zoom without panning
  outOnly?: boolean; // Only zoom out, never in
};

Selection

nvl.getSelectedNodes(): (Node & Point)[]
nvl.getSelectedRelationships(): Relationship[]
nvl.deselectAll(): void

Node Positioning

nvl.setNodePositions(data: Node[], updateLayout?: boolean): void
nvl.pinNode(nodeId: string): void
nvl.unPinNode(nodeIds: string[]): void

Layout

nvl.setLayout(layout: Layout): void
nvl.setLayoutOptions(options: LayoutOptions): void
nvl.isLayoutMoving(): boolean

Export

nvl.saveToFile(options?: { backgroundColor?: string; filename?: string }): void
nvl.saveFullGraphToLargeFile(options?: { backgroundColor?: string; filename?: string }): void
nvl.getImageDataUrl(options?: { backgroundColor?: string }): string

Hit Detection

nvl.getHits(
  evt: MouseEvent,
  targets?: ('node' | 'relationship')[],
  hitOptions?: { hitNodeMarginWidth: number }
): NvlMouseEvent

Lifecycle

nvl.restart(options?: NvlOptions, retainPositions?: boolean): void
nvl.destroy(): void                        // MUST call on unmount
nvl.getCurrentOptions(): NvlOptions
nvl.getContainer(): HTMLElement
nvl.setRenderer(renderer: string): void
nvl.setDisableWebGL(disabled?: boolean): void  // Experimental

ExternalCallbacks (lifecycle hooks)

interface ExternalCallbacks {
  onError?: (error: Error) => void;
  onInitialization?: () => void;
  onLayoutComputing?: (isComputing: boolean) => void;
  onLayoutDone?: () => void;
  onLayoutStep?: (nodes: Node[]) => void;
  onWebGLContextLost?: (event: WebGLContextEvent) => void;
  onZoomTransitionDone?: () => void;
  restart?: () => void;
}

---

9. Patterns (from FinSight)

Label-based node style registry

Centralized config mapping node labels to visual properties:

type NodeStyleConfig = {
  icon: string; // Lucide icon name
  baseColor: string; // Hex color
  baseSize: number; // Node size
  shape: string;
};

const nodeStyleConfig: Record<string, NodeStyleConfig> = {
  Customer: {
    icon: "User",
    baseColor: "#3B82F6",
    baseSize: 30,
    shape: "circle",
  },
  Account: {
    icon: "Landmark",
    baseColor: "#10B981",
    baseSize: 28,
    shape: "circle",
  },
  Transaction: {
    icon: "ArrowLeftRight",
    baseColor: "#F59E0B",
    baseSize: 24,
    shape: "circle",
  },
  // ...
};

function getNodeStyleConfig(label: string): NodeStyleConfig {
  return nodeStyleConfig[label] ?? defaultConfig;
}

Lucide icon → SVG data URI with caching

NVL icon expects a URL or data URI. Convert Lucide React components:

import { renderToStaticMarkup } from 'react-dom/server';

const iconCache = new Map<string, string>();

function getCachedIconDataUri(iconName: string, color: string): string {
  const key = `${iconName}-${color}`;
  if (iconCache.has(key)) return iconCache.get(key)!;

  const IconComponent = getLucideIcon(iconName);
  const svgString = renderToStaticMarkup(<IconComponent color={color} size={24} />);
  const dataUri = `data:image/svg+xml,${encodeURIComponent(svgString)}`;
  iconCache.set(key, dataUri);
  return dataUri;
}

Critical: Pass '#000000' (black) as the icon color. NVL handles color inversion for dark node backgrounds automatically.

Node display name formatting

Format captions based on node label:

function getNodeDisplayName(node: GraphNode): string {
  const label = getPrimaryLabel(node);
  switch (label) {
    case "Customer":
      return `${node.properties.firstName} ${node.properties.lastName}`;
    case "Account":
      return `Account ***${node.properties.accountNumber?.slice(-4)}`;
    case "Transaction":
      return `TXN-${node.properties.amount}`;
    case "Email":
      return node.properties.address;
    case "Phone":
      return node.properties.number;
    default:
      return node.properties.name ?? node.id;
  }
}

Visibility filtering

Filter out removed/hidden nodes before passing to NVL:

const visibleNodes = nodes.filter((n) => !removedNodeIds.has(n.id));
const visibleRelationships = relationships.filter(
  (r) => !removedNodeIds.has(r.source) && !removedNodeIds.has(r.target),
);
// Hidden (but not removed) nodes: pass to NVL with disabled: true

Minimap setup

Create the minimap container via useLayoutEffect (before NVL initializes), then pass as option:

const [minimapElement, setMinimapElement] = useState<HTMLDivElement | null>(null);

useLayoutEffect(() => {
  const minimapDiv = document.createElement('div');
  minimapDiv.className = 'absolute bottom-4 right-4 w-64 h-64 rounded-lg border bg-white';
  minimapDiv.style.pointerEvents = 'auto';
  graphContainerRef.current!.appendChild(minimapDiv);
  setMinimapElement(minimapDiv);
  return () => { minimapDiv.remove(); setMinimapElement(null); };
}, []);

// Pass to NVL — only render when element is ready
const nvlOptions = useMemo(() => ({
  minimapContainer: minimapElement || undefined,
}), [minimapElement]);

// Guard rendering on minimapElement
{nvlNodes.length > 0 && minimapElement ? (
  <InteractiveNvlWrapper nvlOptions={nvlOptions} ... />
) : null}

Stats bar

Show node/relationship counts above the graph:

<div className="border-b px-4 py-2 flex items-center gap-4 text-sm">
  <div>
    Nodes: <span className="font-medium">{visibleNodes.length}</span>
  </div>
  <div>
    Relationships:{" "}
    <span className="font-medium">{visibleRelationships.length}</span>
  </div>
  {hiddenCount > 0 && (
    <div>
      Hidden: <span className="text-orange-600">{hiddenCount}</span>
    </div>
  )}
</div>

Layout change with setTimeout guard

NVL needs a tick to initialize before setLayout calls work:

useEffect(() => {
  if (!nvlRef.current) return;
  const timer = setTimeout(() => {
    nvlRef.current?.setLayout(layout);
  }, 50);
  return () => clearTimeout(timer);
}, [layout]);

Resize handling

Hide graph during panel resize to avoid NVL rendering glitches, show on release:

<div style={{
  opacity: isResizing ? 0 : 1,
  pointerEvents: isResizing ? 'none' : 'auto',
  transition: 'opacity 0.15s ease-out'
}}>
  <InteractiveNvlWrapper ... />
</div>
{isResizing && (
  <div className="absolute inset-0 flex items-center justify-center">
    <p>Release to view graph</p>
  </div>
)}

Zoom controls via ref

const handleZoomIn = useCallback(() => {
  if (nvlRef.current) {
    nvlRef.current.setZoom(nvlRef.current.getScale() * 1.2);
  }
}, []);

const handleFitView = useCallback(() => {
  if (nvlRef.current && visibleNodes.length > 0) {
    nvlRef.current.fit(visibleNodes.map((n) => n.id));
  }
}, [visibleNodes]);

Export image

const handleExportImage = useCallback(() => {
  if (nvlRef.current) {
    const timestamp = new Date()
      .toISOString()
      .replace(/[:.]/g, "-")
      .slice(0, -5);
    nvlRef.current.saveToFile({ filename: `graph-${timestamp}.png` });
  }
}, []);

---

10. Anti-Patterns

Anti-Pattern	Why It Fails	Fix
Missing container height	NVL renders into a 0-height div and nothing appears	Ensure parent has explicit height (h-full, flex-1, or fixed px)
Setting both caption and captions	captions array wins and caption is ignored silently	Use one or the other
Non-black icons	NVL expects black SVGs; it applies node color automatically	Always pass color: '#000000' when generating icon data URIs
Non-square icon images	Icons render distorted	Use square images/SVGs (e.g. 24x24)
Forgetting destroy() on unmount	Memory leak — canvas, event listeners, workers stay alive	Call nvl.destroy() in cleanup (React wrappers handle this)
WebGL renderer + captions/arrowheads	Some caption and arrowhead features only work with canvas renderer	Use renderer: 'canvas' when captions or arrowheads are needed
Calling setLayout immediately after init	NVL hasn't finished initializing — call is silently dropped	Wrap in setTimeout(() => {}, 50) or use onInitialization callback
Arbitrary waitForTimeout for layout	Brittle timing — may fire too early or too late	Use isLayoutMoving() or the onLayoutDone callback instead
Non-unique IDs across nodes and relationships	NVL requires IDs unique across the entire graph — not just within nodes or rels	Prefix or namespace IDs if source data may collide
Mutating node/rel arrays in place	React wrappers diff by reference — mutations are invisible	Always create new arrays: [...nodes] or .map()