API Reference

Complete reference of all public classes, methods, and configuration options.

What's New

Surfaces added since the initial reference. See linked sections below for full details.

New `CreateConfig` options

Option	Type	Default	Notes
`edgeBundling`	`boolean \| 'fdeb' \| 'merge' \| object`	`false`	Edge bundling. `true` auto-pivots fdeb→merge at ≥150 edges. See Edge Bundling.
`autoFitOnChange`	`boolean`	`true`	Re-fit viewport on `batch:end` / `focus:edge-filter` / `focus:pin` / `focus:release`. Suppressed when the viewport is user-dirty (manual pan / zoom / pinch).
`hideOrphans`	`boolean`	`false`	Hide non-combo nodes with zero visible incident edges. See Filtering.
`autoCollapseCombosForce`	`boolean`	`false`	Bypass the “user already collapsed something” guard so force layouts always honor `autoCollapseCombosThreshold`.
`comboEdgeAggregation`	`boolean`	`true`	Synthesize cross-boundary edges between visible collapse-roots. Set `false` to drop them.
`legend.groupEdgesBy`	`string \| callback`	auto-detect	Opts into the edge-type filter section of the Legend. Auto-detect probes `type → category → role → kind → class`.
`minimap.mode`	`'dots' \| 'heatmap' \| 'both'`	`'dots'`	Heatmap modes suppress edges. See Minimap modes.
`layoutOptions.comboStrength`	`number`	`0.15`	combo-force layout: centroid spring.
`layoutOptions.comboRepelStrength`	`number`	`0.5`	combo-force layout: inter-combo repulsion.
`layoutOptions.comboMinMembers`	`number`	`2`	combo-force layout: combos below this size skip both extra passes.

New public methods

Method	Where	Notes
`renderer.requestAutoFit()`	`CanvasRenderer`	Debounced auto-fit. Honors the viewport user-dirty flag.
`renderer.getSynthesizedComboEdges()`	`CanvasRenderer`	Returns the current synthetic `__combo_edge_*` edges (empty when no combos collapsed).
`legend.toggleCategory(key)`	`Legend`	Toggle visibility of all nodes in node group `key`.
`legend.toggleEdgeCategory(key)`	`Legend`	Fade/restore all edges in edge group `key`. Emits `focus:edge-filter`.
`createAutoFitOnChangeApplier(graph, renderer)`	top-level export	Returns an object with a `destroy()` method. Wires the `autoFitOnChange` behavior.
`computeLegendBodyMaxHeight(args)`	top-level export	Pure helper for legend ↔ minimap clearance. Returns `number \| null`.
`computeHeatmapDensity(nodes, bounds, gridSize)`	top-level export	Grid-aggregated density for minimap heatmap mode.
`sampleHeatmapColor(palette, t)`	top-level export	Interpolated color from a cold-to-hot palette at `t` in `[0, 1]`.

New public events

Event	Payload	Fired When
`focus:pin`	`nodeId, hops`	A node is pinned via pinned-focus / clickable legend.
`focus:release`	`undefined`	Pinned focus is released.
`focus:edge-filter`	`hiddenTypes: string[]`	Edge-type filter changes. Payload is the current full hidden-set, not a diff.

New globals / build metadata

window.GraphKit.VERSION — injected at build time as <semver>+<sha>[-dirty] (e.g. 0.9.0+384b375). Useful for in-browser debugging and bug reports. In Node / unbundled test contexts the symbol falls back to '0.0.0-dev'.
VERSION from @graphkit/core — same string, importable for non-IIFE consumers.

create(container, config)

TypeScript

import { create } from '@topokit/renderer-canvas';

const app = create(container: HTMLElement, config: CreateConfig);

CreateConfig

Property	Type	Description
`nodes`	`Node[]`	Initial node array
`edges`	`Edge[]`	Initial edge array
`graph`	`Graph`	Pre-built graph (overrides nodes/edges)
`layout`	`string`	Layout algorithm name
`layoutOptions`	`object`	Options passed to layout algorithm
`layoutRunner`	`LayoutRunnerFn`	Custom layout runner (e.g., Web Worker)
`theme`	`string \| ThemeConfig`	Theme name or custom object
`directed`	`boolean`	Enable directed edges
`interactive`	`boolean`	Enable pan, zoom, drag
`autoResize`	`boolean`	Auto-resize on container resize
`license`	`string`	License key
`whiteLabel`	`boolean`	Remove branding (Enterprise)
`minimap`	`MinimapConfig`	Minimap configuration
`toolbar`	`ToolbarConfig`	Toolbar configuration
`search`	`SearchConfig`	Search bar configuration
`tooltip`	`TooltipConfig`	Tooltip configuration
`contextMenu`	`ContextMenuConfig`	Context menu configuration
`infoPanel`	`InfoPanelConfig`	Info panel configuration
`legend`	`LegendConfig`	Legend configuration
`edgeBundling`	`boolean \| 'fdeb' \| 'merge' \| EdgeBundlingOptions`	Edge bundling (see What's New).
`autoFitOnChange`	`boolean`	Re-fit viewport on graph / focus changes (default `true`).
`hideOrphans`	`boolean`	Hide non-combo nodes with no visible incident edges (default `false`).
`autoCollapseCombosForce`	`boolean`	Force layouts always honor `autoCollapseCombosThreshold` (default `false`).
`comboEdgeAggregation`	`boolean`	Synthesize cross-boundary combo edges (default `true`).

App Instance

Property / Method	Type	Description
`app.graph`	`Graph`	Underlying graph instance
`app.renderer`	`CanvasRenderer`	Canvas renderer instance
`app.setLayout(name, options?)`	`void`	Switch layout algorithm
`app.setTheme(name \| config)`	`void`	Switch theme
`app.bundleEdges(options?)`	`void`	Enable edge bundling at runtime
`app.unbundleEdges()`	`void`	Disable edge bundling
`app.legend`	`Legend`	Legend component instance (when enabled). Exposes `toggleCategory` / `toggleEdgeCategory`.
`app.setMinimap(config)`	`void`	Update minimap
`app.setToolbar(config)`	`void`	Update toolbar
`app.setSearch(config)`	`void`	Update search
`app.setTooltip(config)`	`void`	Update tooltip
`app.setLegend(config)`	`void`	Update legend
`app.destroy()`	`void`	Clean up all resources

Graph Class

TypeScript

import { Graph } from '@topokit/core';
const graph = new Graph(options?);

Node Operations

Method	Returns	Description
`addNode(node)`	`void`	Add a node
`removeNode(id)`	`void`	Remove node and its edges
`updateNode(id, changes)`	`void`	Merge changes into node
`getNode(id)`	`Node \| undefined`	Get node by ID
`getNodes()`	`Node[]`	Get all nodes
`getNodeCount()`	`number`	Total node count
`hasNode(id)`	`boolean`	Check existence
`getNeighbors(id)`	`Node[]`	Get neighboring nodes
`getDegree(id)`	`number`	Connection count

Edge Operations

Method	Returns	Description
`addEdge(edge)`	`void`	Add an edge
`removeEdge(id)`	`void`	Remove an edge
`updateEdge(id, changes)`	`void`	Merge changes into edge
`getEdge(id)`	`Edge \| undefined`	Get edge by ID
`getEdges()`	`Edge[]`	Get all edges
`getEdgeCount()`	`number`	Total edge count
`getEdgesBetween(a, b)`	`Edge[]`	Edges between two nodes
`getNodeEdges(nodeId)`	`Edge[]`	All edges of a node

Filter & Highlight

Method	Returns	Description
`filter(predicate)`	`void`	Hide non-matching nodes
`resetFilter()`	`void`	Show all hidden nodes
`highlightByPredicate(fn, opts?)`	`void`	Dim non-matching nodes
`highlightNodes(ids)`	`void`	Highlight by ID array
`resetHighlight()`	`void`	Reset all highlighting

Progressive Expand

Method	Returns	Description
`initExpand(options)`	`void`	Enter expand mode with seeds
`expand(nodeId)`	`void`	Reveal neighbors
`collapse(nodeId)`	`void`	Hide neighbors
`expandAll()`	`void`	Reveal all
`collapseAll()`	`void`	Collapse to seeds
`resetExpand()`	`void`	Exit expand mode

Clustering

Method	Returns	Description
`cluster(options)`	`void`	Group nodes by field or function
`uncluster()`	`void`	Restore ungrouped graph

Batch & Events

Method	Returns	Description
`batch(fn)`	`void`	Atomic multi-change operation
`on(event, handler)`	`() => void`	Subscribe (returns unsub fn)
`off(event, handler)`	`void`	Unsubscribe

Static Methods

Method	Returns	Description
`Graph.fromData(data, mapping)`	`Graph`	Create graph from JSON with mapping config

CanvasRenderer

Accessed via app.renderer.

Method	Returns	Description
`render()`	`void`	Force re-render
`fitToScreen(padding?)`	`void`	Zoom to fit graph
`zoomTo(level)`	`void`	Set zoom (1.0 = 100%)
`panTo(x, y)`	`void`	Pan viewport to coordinates
`centerOnNode(nodeId)`	`void`	Center on a node
`getZoom()`	`number`	Current zoom level
`getViewport()`	`Rect`	Current viewport bounds
`toImage(format?, quality?)`	`Promise<Blob>`	Export canvas as image
`resize(w, h)`	`void`	Manual canvas resize
`requestAutoFit()`	`void`	Debounced re-fit. Honors viewport user-dirty flag.
`getSynthesizedComboEdges()`	`GraphEdge[]`	Current synthetic `__combo_edge_*` edges; empty when no combos collapsed.
`destroy()`	`void`	Clean up renderer

React Hooks & Components

useGraph(config)

TypeScript

import { useGraph } from '@topokit/react';

const { graph, renderer } = useGraph({
  nodes: [...],
  edges: [...],
  layout: 'force',
  theme: 'dark',
});

Return	Type	Description
`graph`	`Graph`	Stable graph instance
`renderer`	`RefObject<CanvasRenderer>`	Renderer ref (available after mount)

useRenderer()

TypeScript

import { useRenderer } from '@topokit/react';

function Controls() {
  const renderer = useRenderer();
  return <button onClick={() => renderer.fitToScreen()}>Fit</button>;
}

GraphCanvas

TypeScript

import { GraphCanvas } from '@topokit/react';

<GraphCanvas
  graph={graph}
  renderer={renderer}
  style={{ width: '100%', height: '600px' }}
  onNodeClick={(node) => console.log(node)}
  onEdgeClick={(edge) => console.log(edge)}
/>

Prop	Type	Description
`graph`	`Graph`	Graph from `useGraph`
`renderer`	`RefObject`	Renderer ref from `useGraph`
`style`	`CSSProperties`	Container styles
`className`	`string`	CSS class
`onNodeClick`	`(node) => void`	Node click handler
`onNodeDoubleClick`	`(node) => void`	Double-click handler
`onEdgeClick`	`(edge) => void`	Edge click handler
`onCanvasClick`	`() => void`	Canvas click handler
`onSelectionChange`	`(selection) => void`	Selection change handler

Core Types

TypeScript

interface Node {
  id: string;
  data: Record<string, any>;
  position?: { x: number; y: number };
  style?: Partial<NodeStyle>;
}

interface Edge {
  id: string;
  source: string;
  target: string;
  data: Record<string, any>;
  style?: Partial<EdgeStyle>;
}

interface NodeStyle {
  shape: 'circle' | 'rect' | 'diamond' | 'hexagon' | 'triangle';
  fill: string;
  stroke: string;
  radius: number;
  label: string;
  fontSize: number;
  fontColor: string;
  opacity: number;
  icon: string;
  badges: NodeBadge[];
}

interface EdgeStyle {
  type: 'line' | 'curve' | 'step';
  stroke: string;
  width: number;
  arrow: boolean;
  dashed: boolean;
  animated: boolean;
  label: string;
  opacity: number;
}

interface NodeBadge {
  text: string;
  color: string;
  background: string;
  position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
  shape: 'circle' | 'rect';
  icon?: 'dot' | 'alert' | 'check' | 'star';
}

API Reference

What's New

New CreateConfig options

New public methods

New public events

New globals / build metadata

create(container, config)

CreateConfig

App Instance

Graph Class

Node Operations

Edge Operations

Filter & Highlight

Progressive Expand

Clustering

Batch & Events

Static Methods

CanvasRenderer

React Hooks & Components

useGraph(config)

useRenderer()

GraphCanvas

Core Types

New `CreateConfig` options