@graphty/graphty-element / Graph / Graph

Class: Graph

Main orchestrator class for graph visualization and interaction. Integrates Babylon.js scene management, coordinates nodes, edges, layouts, and styling.

Implements

GraphContext

Constructors

Constructor

new Graph(element, useMockInput): Graph

Defined in: src/Graph.ts:133

Creates a new Graph instance and initializes the rendering engine and managers.

Parameters

element

DOM element or element ID to attach the graph canvas to

string | Element

useMockInput

boolean = false

Whether to use mock input for testing (defaults to false)

Returns

Graph

Properties

camera

camera: CameraManager

Defined in: src/Graph.ts:76

canvas

canvas: HTMLCanvasElement

Defined in: src/Graph.ts:73

element

element: Element

Defined in: src/Graph.ts:72

enableDetailedProfiling?

optional enableDetailedProfiling: boolean

Defined in: src/Graph.ts:90

engine

engine: Engine | WebGPUEngine

Defined in: src/Graph.ts:74

eventManager

readonly eventManager: EventManager

Defined in: src/Graph.ts:102

Event manager for adding/removing event listeners

fetchEdges?

optional fetchEdges: FetchEdgesFn

Defined in: src/Graph.ts:87

fetchNodes?

optional fetchNodes: FetchNodesFn

Defined in: src/Graph.ts:86

initialized

initialized: boolean = false

Defined in: src/Graph.ts:88

needRays

needRays: boolean = true

Defined in: src/Graph.ts:82

operationQueue

operationQueue: OperationQueueManager

Defined in: src/Graph.ts:113

pinOnDrag?

optional pinOnDrag: boolean

Defined in: src/Graph.ts:84

runAlgorithmsOnLoad

runAlgorithmsOnLoad: boolean = false

Defined in: src/Graph.ts:89

scene

scene: Scene

Defined in: src/Graph.ts:75

skybox?

optional skybox: string

Defined in: src/Graph.ts:80

styles

styles: Styles

Defined in: src/Graph.ts:70

xrHelper

xrHelper: WebXRDefaultExperience | null = null

Defined in: src/Graph.ts:81

Accessors

input

Get Signature

get input(): InputManager

Defined in: src/Graph.ts:2072

Get the input manager

Returns

InputManager

The input manager instance

Methods

addDataFromSource()

addDataFromSource(type, opts): Promise<void>

Defined in: src/Graph.ts:774

Adds graph data from a registered data source.

Parameters

type

string

Type/name of the registered data source

opts

object = {}

Options to pass to the data source

Returns

Promise<void>

Promise that resolves when data is loaded

addEdge()

addEdge(edge, srcIdPath?, dstIdPath?, options?): Promise<void>

Defined in: src/Graph.ts:996

Add a single edge to the graph.

Parameters

edge

AdHocData

Edge data object to add

srcIdPath?

string

Key to use for edge source ID (default: "source")

dstIdPath?

string

Key to use for edge destination ID (default: "target")

options?

QueueableOptions

Queue options for operation ordering

Returns

Promise<void>

addEdges()

addEdges(edges, srcIdPath?, dstIdPath?, options?): Promise<void>

Defined in: src/Graph.ts:1037

Add edges to the graph incrementally.

Parameters

edges

Record<string | number, unknown>[]

Array of edge data objects to add

srcIdPath?

string

Path to source node ID in edge data (default: "source")

dstIdPath?

string

Path to target node ID in edge data (default: "target")

options?

QueueableOptions

Queue options for operation ordering

Returns

Promise<void>

Promise that resolves when edges are added

Remarks

This method ADDS edges to the existing graph without removing existing edges. Source and target nodes should exist before adding edges, otherwise the edges will reference non-existent nodes.

Edges connect nodes and can optionally store additional data accessible via edge.data.

Since

1.0.0

See

addNodes for adding nodes first
Data Loading Examples

Example

typescript

// Add edges with default source/target fields
await graph.addEdges([
  { source: 'node-1', target: 'node-2', weight: 1.5 },
  { source: 'node-2', target: 'node-3', weight: 2.0 }
]);

// Add edges with custom field names
await graph.addEdges(
  [{ from: 'a', to: 'b', label: 'connects' }],
  'from',
  'to'
);

// Add nodes and edges together
await graph.addNodes([{id: 'a'}, {id: 'b'}]);
await graph.addEdges([{source: 'a', target: 'b'}]);

addListener()

addListener(type, cb): void

Defined in: src/Graph.ts:1491

Add an event listener for graph events.

Parameters

type

EventType

Event type to listen for

cb

EventCallbackType

Callback function to execute when event fires

Returns

void

addNode()

addNode(node, idPath?, options?): Promise<void>

Defined in: src/Graph.ts:928

Add a single node to the graph.

Parameters

node

AdHocData

Node data object to add

idPath?

string

Key to use for node ID (default: "id")

options?

QueueableOptions

Queue options for operation ordering

Returns

Promise<void>

addNodes()

addNodes(nodes, idPath?, options?): Promise<void>

Defined in: src/Graph.ts:967

Add nodes to the graph incrementally.

Parameters

nodes

Record<string | number, unknown>[]

Array of node data objects to add

idPath?

string

Key to use for node IDs (default: "id")

options?

QueueableOptions

Queue options for operation ordering

Returns

Promise<void>

Promise that resolves when nodes are added

Remarks

This method ADDS nodes to the existing graph without removing existing nodes. For complete replacement, use the nodeData property on the web component instead.

Nodes are added to the current layout and will animate into position if a force-directed layout is active.

Since

1.0.0

See

addEdges for adding edges
Data Loading Examples

Example

typescript

// Add nodes with default ID field
await graph.addNodes([
  { id: 'node-1', label: 'First Node', category: 'A' },
  { id: 'node-2', label: 'Second Node', category: 'B' }
]);

// Add nodes with custom ID field
await graph.addNodes(
  [{ nodeId: 'n1', name: 'Node One' }],
  'nodeId'
);

// Wait for layout to settle after adding
await graph.addNodes(newNodes);
await graph.waitForSettled();
graph.zoomToFit();

aiCommand()

aiCommand(input): Promise<ExecutionResult>

Defined in: src/Graph.ts:3726

Send a natural language command to the AI controller.

Parameters

input

string

Natural language command (e.g., "switch to circular layout")

Returns

Promise<ExecutionResult>

Promise resolving to command result

Example

typescript

// Query graph info
const result = await graph.aiCommand('How many nodes are there?');
console.log(result.message);

// Change layout
await graph.aiCommand('Use circular layout');

// Switch dimension
await graph.aiCommand('Show in 2D');

applySuggestedStyles()

applySuggestedStyles(algorithmKey, options?): boolean

Defined in: src/Graph.ts:1202

Apply suggested styles from an algorithm

Parameters

algorithmKey

Algorithm key (e.g., "graphty:degree") or array of keys

string | string[]

options?

ApplySuggestedStylesOptions

Options for applying suggested styles

Returns

boolean

true if any styles were applied, false otherwise

batchOperations()

batchOperations(fn): Promise<void>

Defined in: src/Graph.ts:1447

Execute multiple operations as a batch Operations will be queued and executed in dependency order

Parameters

fn

() => void | Promise<void>

Function containing operations to batch

Returns

Promise<void>

canCaptureScreenshot()

canCaptureScreenshot(options?): Promise<CapabilityCheck>

Defined in: src/Graph.ts:2262

Check if screenshot can be captured with given options.

Parameters

options?

ScreenshotOptions

Screenshot options to validate

Returns

Promise<CapabilityCheck>

Promise<CapabilityCheck> - Result indicating whether screenshot is supported

Example

typescript

// Check if 4x multiplier is supported
const check = await graph.canCaptureScreenshot({ multiplier: 4 });
if (!check.supported) {
  console.error('Cannot capture:', check.reason);
} else if (check.warnings) {
  console.warn('Warnings:', check.warnings);
}

// Check 8K resolution
const check8k = await graph.canCaptureScreenshot({
  width: 7680,
  height: 4320
});
console.log(`Memory: ${check8k.estimatedMemoryMB.toFixed(0)}MB`);

cancelAiCommand()

cancelAiCommand(): void

Defined in: src/Graph.ts:3791

Cancel any in-progress AI command.

Returns

void

Example

typescript

// Start a long-running command
const promise = graph.aiCommand('complex query');

// Cancel it
graph.cancelAiCommand();

cancelAnimationCapture()

cancelAnimationCapture(): boolean

Defined in: src/Graph.ts:2457

Cancel ongoing animation capture

Returns

boolean

true if a capture was cancelled, false if no capture was in progress

Example

typescript

// Start a capture
const capturePromise = graph.captureAnimation({
  duration: 10000,
  fps: 30,
  cameraMode: 'stationary'
});

// Cancel it after 2 seconds
setTimeout(() => {
  const wasCancelled = graph.cancelAnimationCapture();
  console.log('Cancelled:', wasCancelled);
}, 2000);

// The promise will reject with AnimationCancelledError
try {
  await capturePromise;
} catch (error) {
  if (error.name === 'AnimationCancelledError') {
    console.log('Capture was cancelled');
  }
}

captureAnimation()

captureAnimation(options): Promise<AnimationResult>

Defined in: src/Graph.ts:2304

Capture an animation as a video (stationary or animated camera)

Parameters

options

AnimationOptions

Animation capture options

Returns

Promise<AnimationResult>

Promise resolving to AnimationResult with blob and metadata

Example

typescript

// Basic 5-second video at 30fps
const result = await graph.captureAnimation({
  duration: 5000,
  fps: 30,
  cameraMode: 'stationary'
});

// High-quality 60fps video with download
const result = await graph.captureAnimation({
  duration: 10000,
  fps: 60,
  cameraMode: 'stationary',
  download: true,
  downloadFilename: 'graph-video.webm'
});

// Animated camera path (camera tour)
const result = await graph.captureAnimation({
  duration: 5000,
  fps: 30,
  cameraMode: 'animated',
  cameraPath: [
    { position: { x: 10, y: 10, z: 10 }, target: { x: 0, y: 0, z: 0 } },
    { position: { x: 0, y: 20, z: 0 }, target: { x: 0, y: 0, z: 0 }, duration: 2500 },
    { position: { x: -10, y: 10, z: 10 }, target: { x: 0, y: 0, z: 0 }, duration: 2500 }
  ],
  easing: 'easeInOut',
  download: true
});

captureScreenshot()

captureScreenshot(options?): Promise<ScreenshotResult>

Defined in: src/Graph.ts:2230

Capture a screenshot of the current graph visualization.

Parameters

options?

ScreenshotOptions

Screenshot options (format, resolution, destinations, etc.)

Returns

Promise<ScreenshotResult>

Promise resolving to ScreenshotResult with blob and metadata

Example

typescript

// Basic PNG screenshot
const result = await graph.captureScreenshot();

// High-res JPEG with download
const result = await graph.captureScreenshot({
  format: 'jpeg',
  multiplier: 2,
  destination: { download: true }
});

// Copy to clipboard
const result = await graph.captureScreenshot({
  destination: { clipboard: true }
});

createApiKeyManager()

static createApiKeyManager(): ApiKeyManager

Defined in: src/Graph.ts:3876

Create a standalone ApiKeyManager for key management without enabling AI. Useful for settings UIs that configure keys before AI activation.

Returns

ApiKeyManager

A new ApiKeyManager instance

Example

typescript

// In a settings UI component
const keyManager = Graph.createApiKeyManager();
keyManager.enablePersistence({
  encryptionKey: userSecret,
  storage: 'localStorage',
});
keyManager.setKey('openai', apiKey);

deselectNode()

deselectNode(): void

Defined in: src/Graph.ts:1686

Deselect the currently selected node.

Returns

void

Remarks

Clears the current selection and triggers a selection-changed event. If no node is selected, this is a no-op.

Since

1.0.0

See

selectNode to select a node
getSelectedNode to check current selection

Example

typescript

// Clear selection programmatically
graph.selectNode("node-123");
graph.deselectNode();
console.log(graph.getSelectedNode()); // null

// Clear selection on escape key
document.addEventListener('keydown', (e) => {
  if (e.key === 'Escape') {
    graph.deselectNode();
  }
});

disableAiControl()

disableAiControl(): void

Defined in: src/Graph.ts:3702

Disable AI control and clean up resources.

Returns

void

Example

typescript

graph.disableAiControl();
// AI commands will no longer work

dispose()

dispose(): void

Defined in: src/Graph.ts:4114

Dispose all graph resources including voice, AI, XR, and Babylon.js components.

Returns

void

enableAiControl()

enableAiControl(config): Promise<void>

Defined in: src/Graph.ts:3685

Enable AI-powered natural language control of the graph.

Parameters

config

AiManagerConfig

AI configuration including provider and optional API key

Returns

Promise<void>

Promise resolving when AI is ready

Example

typescript

// Enable with mock provider (for testing)
await graph.enableAiControl({ provider: 'mock' });

// Enable with OpenAI
await graph.enableAiControl({
  provider: 'openai',
  apiKey: 'sk-...'
});

// Now you can send commands
const result = await graph.aiCommand('Show me the graph summary');

enterXR()

enterXR(mode): Promise<void>

Defined in: src/Graph.ts:4043

Enter XR mode (VR or AR)

Parameters

mode

The XR mode to enter ('immersive-vr' or 'immersive-ar')

"immersive-vr" | "immersive-ar"

Returns

Promise<void>

estimateAnimationCapture()

estimateAnimationCapture(options): Promise<CaptureEstimate>

Defined in: src/Graph.ts:2498

Estimate performance and potential issues for animation capture

Parameters

options

Pick<AnimationOptions, "duration" | "fps" | "width" | "height">

Animation options to estimate

Returns

Promise<CaptureEstimate>

Promise resolving to CaptureEstimate

Example

typescript

const estimate = await graph.estimateAnimationCapture({
  duration: 5000,
  fps: 60,
  width: 3840,
  height: 2160
});

if (estimate.likelyToDropFrames) {
  console.warn(`May drop frames. Recommended: ${estimate.recommendedFps}fps`);
}

exitXR()

exitXR(): Promise<void>

Defined in: src/Graph.ts:4086

Exit XR mode and return to previous camera

Returns

Promise<void>

exportCameraPresets()

exportCameraPresets(): Record<string, CameraState>

Defined in: src/Graph.ts:3588

Export user-defined presets as JSON

Returns

Record<string, CameraState>

Object mapping preset names to camera states

getAiManager()

getAiManager(): AiManager | null

Defined in: src/Graph.ts:3808

Get the AI manager for advanced configuration. Returns null if AI is not enabled.

Returns

AiManager | null

The AI manager or null

Example

typescript

const manager = graph.getAiManager();
if (manager) {
  // Register custom command
  manager.registerCommand(myCustomCommand);
}

getAiStatus()

getAiStatus(): AiStatus | null

Defined in: src/Graph.ts:3750

Get the current AI status synchronously.

Returns

AiStatus | null

Current AI status or null if AI is not enabled

Example

typescript

const status = graph.getAiStatus();
if (status?.state === 'executing') {
  console.log('AI is processing a command...');
}

getApiKeyManager()

getApiKeyManager(): ApiKeyManager | null

Defined in: src/Graph.ts:3857

Get the API key manager for configuring keys before enabling AI. Returns null if AI has never been enabled.

Returns

ApiKeyManager | null

The API key manager or null

Example

typescript

const keyManager = graph.getApiKeyManager();
if (keyManager) {
  const providers = keyManager.getConfiguredProviders();
  console.log('Configured providers:', providers);
}

getCameraController()

getCameraController(): CameraController | null

Defined in: src/Graph.ts:2156

Get the active camera controller.

Returns

CameraController | null

The active camera controller or null if none active

getCameraPresets()

getCameraPresets(): Record<string, CameraState | { builtin: true; }>

Defined in: src/Graph.ts:3568

Get all camera presets (built-in + user-defined)

Returns

Record<string, CameraState | { builtin: true; }>

Object mapping preset names to camera states or builtin marker

getCameraState()

getCameraState(): CameraState

Defined in: src/Graph.ts:2507

Get the current camera state

Returns

CameraState

Camera state including position, target, and rotation

getConfig()

getConfig(): GraphContextConfig

Defined in: src/Graph.ts:1976

Get the current graph context configuration.

Returns

GraphContextConfig

The graph context configuration

Implementation of

GraphContext.getConfig

getDataManager()

getDataManager(): DataManager

Defined in: src/Graph.ts:1555

Get the DataManager instance.

Returns

DataManager

The DataManager instance

Implementation of

GraphContext.getDataManager

getEdgeCount()

getEdgeCount(): number

Defined in: src/Graph.ts:1473

Get the total number of edges in the graph.

Returns

number

The number of edges

getEventManager()

getEventManager(): EventManager

Defined in: src/Graph.ts:1611

Get the EventManager instance for event handling.

Returns

EventManager

The EventManager instance

Implementation of

GraphContext.getEventManager

getLayoutManager()

getLayoutManager(): LayoutManager

Defined in: src/Graph.ts:1563

Get the LayoutManager instance.

Returns

LayoutManager

The LayoutManager instance

Implementation of

GraphContext.getLayoutManager

getMeshCache()

getMeshCache(): MeshCache

Defined in: src/Graph.ts:1579

Get the MeshCache instance used for mesh instancing.

Returns

MeshCache

The MeshCache instance

Implementation of

GraphContext.getMeshCache

getNode()

getNode(nodeId): Node | undefined

Defined in: src/Graph.ts:3640

Get a specific node

Parameters

nodeId

ID of the node to retrieve

string | number

Returns

Node | undefined

The node instance or undefined if not found

getNodeCount()

getNodeCount(): number

Defined in: src/Graph.ts:1465

Get the total number of nodes in the graph.

Returns

number

The number of nodes

getNodeMesh()

getNodeMesh(nodeId): AbstractMesh | null

Defined in: src/Graph.ts:2165

Get the Babylon.js mesh for a node by its ID.

Parameters

GraphContext.getScene

getSelectedNode()

getSelectedNode(): Node | null

Defined in: src/Graph.ts:1623

Get the currently selected node.

Returns

Node | null

The selected node, or null if nothing is selected.

getSelectionManager()

getSelectionManager(): SelectionManager

Defined in: src/Graph.ts:1603

Get the SelectionManager instance for handling node selection.

Returns

SelectionManager

The SelectionManager instance

Implementation of

GraphContext.getSelectionManager

getStatsManager()

getStatsManager(): StatsManager

Defined in: src/Graph.ts:1595

Get the StatsManager instance for performance metrics.

Returns

StatsManager

The StatsManager instance

Implementation of

GraphContext.getStatsManager

getStyleManager()

getStyleManager(): StyleManager

Defined in: src/Graph.ts:1547

Get the StyleManager instance.

Returns

StyleManager

The StyleManager instance

Implementation of

GraphContext.getStyleManager

getStyles()

getStyles(): Styles

Defined in: src/Graph.ts:1539

Get the Styles instance for the graph.

Returns

Styles

The Styles instance

getSuggestedStyles()

getSuggestedStyles(algorithmKey): SuggestedStylesConfig | null

VoiceInputAdapter

The voice input adapter

Example

typescript

const adapter = graph.getVoiceAdapter();
if (adapter.isSupported) {
  adapter.start({ continuous: true });
}

getXRConfig()

getXRConfig(): XRConfig | undefined

Defined in: src/Graph.ts:2004

Get the current XR configuration.

Returns

XRConfig | undefined

The XR configuration if set

Implementation of

GraphContext.getXRConfig

getXRSessionManager()

getXRSessionManager(): XRSessionManager | undefined

Defined in: src/Graph.ts:2023

Get the XR session manager instance.

Returns

XRSessionManager | undefined

The XR session manager if XR is initialized

Implementation of

GraphContext.getXRSessionManager

importCameraPresets()

importCameraPresets(presets): void

Defined in: src/Graph.ts:3600

boolean

True if in 2D mode, false otherwise

Deprecated

Use getViewMode() === "2d" instead

Implementation of

GraphContext.is2D

isAiEnabled()

isAiEnabled(): boolean

Defined in: src/Graph.ts:3816

Check if AI control is currently enabled.

Returns

boolean

True if AI is enabled

isAnimationCapturing()

isAnimationCapturing(): boolean

Defined in: src/Graph.ts:2476

Check if an animation capture is currently in progress

Returns

boolean

True if currently capturing an animation

isARSupported()

isARSupported(): Promise<boolean>

Defined in: src/Graph.ts:2059

Check if AR mode is supported on this device/browser. Returns true if WebXR is available and AR sessions are supported.

Returns

Promise<boolean>

Promise resolving to true if AR is supported

Example

typescript

const arSupported = await graph.isARSupported();
if (!arSupported) {
  console.log("AR not available on this device");
}

isNodeSelected()

isNodeSelected(nodeId): boolean

Defined in: src/Graph.ts:1695

Check if a specific node is currently selected.

Parameters

nodeId

The ID of the node to check.

string | number

Returns

boolean

True if the node is selected, false otherwise.

isRunning()

isRunning(): boolean

Defined in: src/Graph.ts:1988

Check if the layout engine is currently running.

Returns

boolean

True if layout is running

Implementation of

GraphContext.isRunning

isVoiceActive()

isVoiceActive(): boolean

Defined in: src/Graph.ts:3979

Check if voice input is currently active.

Returns

boolean

True if voice input is active

isVRSupported()

isVRSupported(): Promise<boolean>

Defined in: src/Graph.ts:2039

Check if VR mode is supported on this device/browser. Returns true if WebXR is available and VR sessions are supported.

Returns

Promise<boolean>

Promise resolving to true if VR is supported

Example

typescript

const vrSupported = await graph.isVRSupported();
if (!vrSupported) {
  console.log("VR not available on this device");
}

listenerCount()

listenerCount(): number

Defined in: src/Graph.ts:1501

Get the total number of registered event listeners. Useful for debugging and testing to ensure listeners are properly cleaned up.

Returns

number

The number of registered listeners

loadCameraPreset()

loadCameraPreset(name, options?): Promise<void>

Defined in: src/Graph.ts:3560

Load a camera preset (built-in or user-defined)

Parameters

name

string

Name of the preset to load

options?

CameraAnimationOptions

Optional animation configuration

Returns

Promise<void>

Promise that resolves when camera state is applied

loadFromFile()

loadFromFile(file, options?): Promise<void>

Defined in: src/Graph.ts:787

Load graph data from a File object with auto-format detection

Parameters

file

File

File object from file input

options?

Loading options

edgeDstIdPath?

string

JMESPath for edge destination ID extraction

edgeSrcIdPath?

string

JMESPath for edge source ID extraction

format?

string

Explicit format override (e.g., "graphml", "json")

nodeIdPath?

string

JMESPath for node ID extraction

Returns

Promise<void>

loadFromUrl()

loadFromUrl(url, options?): Promise<void>

Defined in: src/Graph.ts:854

Load graph data from a URL with auto-format detection

Parameters

url

string

URL to fetch graph data from

options?

Loading options

edgeDstIdPath?

string

JMESPath for edge destination ID extraction

edgeSrcIdPath?

string

JMESPath for edge source ID extraction

format?

string

Explicit format override (e.g., "graphml", "json")

nodeIdPath?

string

JMESPath for node ID extraction

Returns

Promise<void>

Remarks

This method attempts to detect the format from the URL extension first. If the extension is not recognized (e.g., .txt), it fetches the content and uses content-based detection. The content is then passed directly to the data source to avoid a double-fetch.

Example

typescript

// Auto-detect format from extension
await graph.loadFromUrl("https://example.com/data.graphml");

// Auto-detect from content when extension doesn't match
await graph.loadFromUrl("https://example.com/data.txt");

// Explicitly specify format
await graph.loadFromUrl("https://example.com/data.txt", { format: "graphml" });

needsRayUpdate()

needsRayUpdate(): boolean

Defined in: src/Graph.ts:1968

Check if ray updates are needed for edge arrows.

Returns

boolean

True if rays need updating

Implementation of

GraphContext.needsRayUpdate

on()

on(type, cb): void

Defined in: src/Graph.ts:1482

Alias for addEventListener

Parameters

type

EventType

Event type to listen for

cb

EventCallbackType

Callback function to execute when event fires

Returns

void

onAiStatusChange()

onAiStatusChange(callback): () => void

Defined in: src/Graph.ts:3771

Subscribe to AI status changes.

Parameters

callback

StatusChangeCallback

Function called when status changes

Returns

Unsubscribe function

(): void

Returns

void

Example

typescript

const unsubscribe = graph.onAiStatusChange((status) => {
  console.log('AI state:', status.state);
  if (status.streamedText) {
    console.log('Response:', status.streamedText);
  }
});

// Later: stop listening
unsubscribe();

removeNodes()

removeNodes(nodeIds, options?): Promise<void>

Defined in: src/Graph.ts:1308

Remove nodes from the graph by their IDs.

Parameters

nodeIds

(string | number)[]

Array of node IDs to remove

options?

QueueableOptions

Queue options for operation ordering

Returns

Promise<void>

render()

render(): void

Defined in: src/Graph.ts:3655

Render method (public for testing)

Returns

void

resetCamera()

resetCamera(options?): Promise<void>

Defined in: src/Graph.ts:3453

Reset camera to default state

Parameters

options?

CameraAnimationOptions

Optional animation configuration

Returns

Promise<void>

Promise that resolves when camera is reset

resolveCameraPreset()

resolveCameraPreset(preset): CameraState

Defined in: src/Graph.ts:3477

Resolve a camera preset (built-in or user-defined) to a CameraState

Parameters

preset

string

Name of the preset to resolve

Returns

CameraState

The resolved camera state

retryLastAiCommand()

retryLastAiCommand(): Promise<ExecutionResult>

Defined in: src/Graph.ts:3836

Retry the last AI command. Useful for retrying after transient errors.

Returns

Promise<ExecutionResult>

Promise resolving to command result

Throws

Error if AI not enabled or no previous command

Example

typescript

// After a failed command
try {
  const result = await graph.retryLastAiCommand();
  console.log('Retry succeeded:', result);
} catch (error) {
  console.error('Retry failed:', error);
}

runAlgorithm()

runAlgorithm(namespace, type, options?): Promise<void>

Defined in: src/Graph.ts:1166

Run a graph algorithm and store results on nodes/edges.

Parameters

namespace

string

Algorithm namespace (e.g., "graphty")

type

string

Algorithm type (e.g., "degree", "pagerank")

options?

RunAlgorithmOptions

Algorithm options and queue settings

Returns

Promise<void>

Promise that resolves when algorithm completes

Remarks

Algorithms are identified by namespace and type (e.g., graphty:degree). Results are stored on each node's algorithmResults property and can be accessed in style selectors.

Available algorithms by category:

Centrality: degree, betweenness, closeness, pagerank, eigenvector
Community: louvain, label-propagation, leiden
Components: connected-components, strongly-connected
Traversal: bfs, dfs
Shortest Path: dijkstra, bellman-ford
Spanning Tree: prim, kruskal
Flow: max-flow, min-cut

Since

1.0.0

See

applySuggestedStyles to visualize results
Centrality Examples
Community Detection

Example

typescript

// Run degree centrality
await graph.runAlgorithm('graphty', 'degree');

// Access results
const node = graph.getNode('node-1');
console.log('Degree:', node.algorithmResults['graphty:degree']);

// Run with auto-styling
await graph.runAlgorithm('graphty', 'pagerank', {
  algorithmOptions: { damping: 0.85 },
  applySuggestedStyles: true
});

// Use results in style selectors
styleManager.addLayer({
  selector: "[?algorithmResults.'graphty:degree' > `10`]",
  styles: { node: { color: '#ff0000', size: 2.0 } }
});

runAlgorithmsFromTemplate()

runAlgorithmsFromTemplate(): Promise<void>

Defined in: src/Graph.ts:422

Executes all algorithms specified in the style template configuration.

Returns

Promise<void>

saveCameraPreset()

saveCameraPreset(name): void

Defined in: src/Graph.ts:3542

Save current camera state as a named preset

Parameters

name

string

Name for the camera preset

Returns

void

screenToWorld()

screenToWorld(screenPos): { x: number; y: number; z: number; } | null

Defined in: src/Graph.ts:2138

Convert 2D screen coordinates to 3D world coordinates via raycasting.

Parameters

screenPos

Screen position to convert

x

number

X coordinate in screen space

y

number

Y coordinate in screen space

Returns

{ x: number; y: number; z: number; } | null

World coordinates {x, y, z} or null if no intersection

selectNode()

selectNode(nodeId): boolean

Defined in: src/Graph.ts:1659

Select a node by its ID.

Parameters

nodeId

The ID of the node to select

string | number

Returns

boolean

True if the node was found and selected, false if not found

Remarks

Selection triggers a selection-changed event and applies selection styles (defined in the style template). Only one node can be selected at a time; calling this method will deselect any previously selected node.

Selection is often used to:

Show a details panel with node information
Highlight the node and its connections
Enable context-specific actions

Since

1.0.0

See

deselectNode to clear selection
getSelectedNode to get current selection
Selection Examples

Example

typescript

// Select a node and show its details
if (graph.selectNode('node-123')) {
  const node = graph.getSelectedNode();
  console.log('Selected:', node.data);
  showDetailsPanel(node);
}

// Handle click events for selection
graph.on('node-click', ({ node }) => {
  graph.selectNode(node.id);
});

setCameraMode()

setCameraMode(mode, options?): Promise<void>

Defined in: src/Graph.ts:1392

Set the active camera mode (e.g., "arcRotate", "universal").

Parameters

mode

CameraKey

Camera mode key to activate

options?

QueueableOptions

Queue options for operation ordering

Returns

Promise<void>

setCameraPan()

setCameraPan(pan, options?): Promise<void>

Defined in: src/Graph.ts:3441

Set camera pan (2D)

Parameters

pan

Pan offset coordinates

x

number

X offset

y

number

Y offset

options?

CameraAnimationOptions

Optional animation configuration

Returns

Promise<void>

Promise that resolves when pan is set

setCameraPosition()

setCameraPosition(position, options?): Promise<void>

Promise<void>

Promise that resolves when camera position is set

setCameraState()

setCameraState(state, options?): Promise<void>

Defined in: src/Graph.ts:2622

Set the camera state (Phase 4: with animation support)

Parameters

state

Camera state or preset name to apply

CameraState | { preset: string; }

options?

CameraAnimationOptions

Optional animation configuration

Returns

Promise<void>

setCameraTarget()

setCameraTarget(target, options?): Promise<void>

Promise<void>

Promise that resolves when camera target is set

setCameraZoom()

setCameraZoom(zoom, options?): Promise<void>

Defined in: src/Graph.ts:3426

Set camera zoom (2D)

Parameters

zoom

number

Zoom level (1.0 = default, >1 = zoomed in, <1 = zoomed out)

options?

CameraAnimationOptions

Optional animation configuration

Returns

Promise<void>

Promise that resolves when zoom is set

setData()

setData(data): void

Defined in: src/Graph.ts:3617

Set graph data (delegates to data manager)

Parameters

data

Graph data object

edges

Record<string, unknown>[]

Array of edge data objects

nodes

Record<string, unknown>[]

Array of node data objects

Returns

void

setInputEnabled()

setInputEnabled(enabled): void

Defined in: src/Graph.ts:2080

Enable or disable input

Parameters

enabled

boolean

True to enable input, false to disable

Returns

void

setLayout()

setLayout(type, opts, options?): Promise<void>

Defined in: src/Graph.ts:1099

Set the layout algorithm and configuration.

Parameters

type

string

Layout algorithm name

opts

object = {}

Layout-specific configuration options

options?

QueueableOptions

Options for operation queue behavior

Returns

Promise<void>

Promise that resolves when layout is initialized

Remarks

Available layouts:

ngraph: Force-directed (3D optimized, recommended for general use)
d3-force: Force-directed (2D, web standard)
circular: Nodes arranged in a circle
grid: Nodes arranged in a grid
hierarchical: Tree/DAG layout
random: Random positions (useful for testing)
fixed: Use pre-defined positions from node data

Layout changes are queued and execute in order. The layout will animate nodes from their current positions to new positions.

Since

1.0.0

See

waitForSettled to wait for layout completion
3D Layout Examples
2D Layout Examples

Example

typescript

// Use force-directed layout with custom settings
await graph.setLayout('ngraph', {
  springLength: 100,
  springCoefficient: 0.0008,
  gravity: -1.2,
  dimensions: 3
});

// Wait for layout to settle then zoom to fit
await graph.waitForSettled();
graph.zoomToFit();

// Switch to circular layout
await graph.setLayout('circular', { radius: 5 });

setRenderSettings()

setRenderSettings(settings, options?): Promise<void>

Defined in: src/Graph.ts:1419

Update rendering settings for the graph visualization.

Parameters

settings

Record<string, unknown>

Object containing rendering configuration options

options?

QueueableOptions

Queue options for operation ordering

Returns

Promise<void>

setRunning()

setRunning(running): void

Defined in: src/Graph.ts:1996

Set whether the layout engine should run.

Parameters

running

boolean

True to start the layout, false to stop it

Returns

void

Implementation of

GraphContext.setRunning

setStyleTemplate()

setStyleTemplate(t, options?): Promise<Styles>

Defined in: src/Graph.ts:577

Sets the style template for the graph, applying visual and behavioral configurations.

View mode controls how the graph is rendered and displayed.

"2d": Orthographic camera, fixed top-down view
"3d": Perspective camera with orbit controls (default)
"ar": Augmented reality mode using WebXR
"vr": Virtual reality mode using WebXR

options?

QueueableOptions

Optional queueing options for batch processing

Returns

Promise<Styles>

The updated Styles instance

setViewMode()

setViewMode(mode, options?): Promise<void>

Defined in: src/Graph.ts:1778

Set the view mode. This controls the camera type, input handling, and rendering approach.

Parameters

mode

The view mode to set: "2d", "3d", "ar", or "vr"

"2d" | "3d" | "ar" | "vr"

options?

QueueableOptions

Optional queueing options

Returns

Promise<void>

Promise that resolves when view mode is set

Example

typescript

// Switch to 2D orthographic view
await graph.setViewMode("2d");

// Switch to VR mode
await graph.setViewMode("vr");

setXRConfig()

setXRConfig(config): void

Defined in: src/Graph.ts:2013

Set XR configuration. Merges with defaults and updates the graph context.

Parameters

config

Partial XR configuration to apply

{ ar?: { enabled?: boolean; optionalFeatures?: string[]; referenceSpaceType?: "local" | "local-floor" | "bounded-floor" | "unbounded"; }; enabled?: boolean; input?: { controllers?: boolean; enableZAmplificationInDesktop?: boolean; handTracking?: boolean; nearInteraction?: boolean; physics?: boolean; zAxisAmplification?: number; }; teleportation?: { easeTime?: number; enabled?: boolean; }; ui?: { enabled?: boolean; position?: "top-right" | "top-left" | "bottom-left" | "bottom-right"; showAvailabilityWarning?: boolean; unavailableMessageDuration?: number; }; vr?: { enabled?: boolean; optionalFeatures?: string[]; referenceSpaceType?: "local" | "local-floor" | "bounded-floor" | "unbounded"; }; }

Partial XR configuration to apply

ar?

{ enabled?: boolean; optionalFeatures?: string[]; referenceSpaceType?: "local" | "local-floor" | "bounded-floor" | "unbounded"; } = ...

AR mode configuration

ar.enabled?

boolean = ...

Enable AR mode

Default

true

ar.optionalFeatures?

string[] = ...

Optional WebXR features to request

Default

["hit-test"]

ar.referenceSpaceType?

"local" | "local-floor" | "bounded-floor" | "unbounded" = ...

WebXR reference space type for AR

Default

"local-floor"

enabled?

boolean = ...

Enable/disable XR functionality globally

Default

true

input?

{ controllers?: boolean; enableZAmplificationInDesktop?: boolean; handTracking?: boolean; nearInteraction?: boolean; physics?: boolean; zAxisAmplification?: number; } = ...

XR input and interaction configuration

input.controllers?

boolean = ...

Enable motion controllers

Default

true

input.enableZAmplificationInDesktop?

boolean = ...

Enable Z-axis amplification in desktop mode Normally amplification only applies in XR mode, but this can enable it for desktop too

Default

false

input.handTracking?

boolean = ...

Enable hand tracking

Default

true

input.nearInteraction?

boolean = ...

Enable near interaction (touch/grab)

Default

true

input.physics?

boolean = ...

Enable physics-based interactions

Default

false

input.zAxisAmplification?

number = ...

Z-axis movement amplification factor Multiplies Z-axis delta during drag to make depth manipulation practical in VR

Example: With zAxisAmplification = 10, moving controller 0.1 units in Z will move the node 1.0 units in Z

Default

10.0

teleportation?

{ easeTime?: number; enabled?: boolean; } = ...

Teleportation configuration

teleportation.easeTime?

number = ...

Teleportation animation duration (ms)

Default

teleportation.enabled?

boolean = ...

Enable teleportation system

Default

false

ui?

{ enabled?: boolean; position?: "top-right" | "top-left" | "bottom-left" | "bottom-right"; showAvailabilityWarning?: boolean; unavailableMessageDuration?: number; } = ...

XR UI button configuration

ui.enabled?

boolean = ...

Show VR/AR entry buttons

Default

true

ui.position?

"top-right" | "top-left" | "bottom-left" | "bottom-right" = ...

Button position on screen

Default

"bottom-right"

ui.showAvailabilityWarning?

boolean = ...

Show "VR / AR NOT AVAILABLE" warning when XR is not available When false, no message is displayed if AR/VR aren't available

Default

false

ui.unavailableMessageDuration?

number = ...

Duration to show "not available" message (ms)

Default

vr?

{ enabled?: boolean; optionalFeatures?: string[]; referenceSpaceType?: "local" | "local-floor" | "bounded-floor" | "unbounded"; } = ...

VR mode configuration

vr.enabled?

boolean = ...

Enable VR mode

Default

true

vr.optionalFeatures?

string[] = ...

Optional WebXR features to request

Default

[]

vr.referenceSpaceType?

"local" | "local-floor" | "bounded-floor" | "unbounded" = ...

WebXR reference space type for VR

"local": Seated/standing experience, no room bounds
"local-floor": Floor-level origin, no room bounds
"bounded-floor": Room-scale with bounds
"unbounded": Unlimited tracking space

Default

"local-floor"

| undefined

Returns

void

shutdown()

shutdown(): void

Defined in: src/Graph.ts:399

Shuts down the graph, stopping animations and disposing all resources.

Returns

void

startInputRecording()

startInputRecording(): void

Defined in: src/Graph.ts:2087

Start recording input for testing/automation

Returns

void

startVoiceInput()

startVoiceInput(options?): boolean

Defined in: src/Graph.ts:3928

Start voice input and execute commands.

Parameters

options?

Voice input options

continuous?

boolean

Whether to continuously listen for input

interimResults?

boolean

Whether to return interim transcription results

language?

string

BCP 47 language tag (e.g., "en-US", "fr-FR")

onStart?

(started, error?) => void

Callback when voice input starts

onTranscript?

(text, isFinal) => void

Callback for transcription events

Returns

boolean

True if voice input started successfully

Example

typescript

graph.startVoiceInput({
  continuous: true,
  interimResults: true,
  onTranscript: (text, isFinal) => {
    console.log('Transcript:', text, isFinal ? '(final)' : '(interim)');
    if (isFinal) {
      graph.aiCommand(text);
    }
  },
});

stopInputRecording()

stopInputRecording(): RecordedInputEvent[]

Defined in: src/Graph.ts:2095

Stop recording and get recorded events

Returns

RecordedInputEvent[]

Array of recorded input events

stopVoiceInput()

stopVoiceInput(): void

Defined in: src/Graph.ts:3971

Stop voice input.

Returns

void

Example

typescript

graph.stopVoiceInput();

update()

update(): void

Defined in: src/Graph.ts:508

Update method - kept for backward compatibility All update logic is now handled by UpdateManager

Returns

void

updateNodes()

updateNodes(updates, options?): Promise<void>

Defined in: src/Graph.ts:1349

Update node data for existing nodes in the graph.

Parameters

updates

object[]

Array of update objects containing node ID and properties to update

options?

QueueableOptions

Queue options for operation ordering

Returns

Promise<void>

waitForSettled()

waitForSettled(): Promise<void>

Defined in: src/Graph.ts:2203

Wait for the graph operations to complete and layout to stabilize.

Returns

Promise<void>

Promise that resolves when all operations are complete

Remarks

This method waits for all queued operations (data loading, layout changes, algorithm execution) to complete. Use this before taking screenshots, exporting data, or performing actions that require the graph to be stable.

The method returns when:

All queued operations have completed
The operation queue is empty

Since

1.0.0

See

zoomToFit to zoom after settling
captureScreenshot for capturing stable views

Example

typescript

// Wait for layout to settle before zooming
await graph.addNodes(nodes);
await graph.addEdges(edges);
await graph.waitForSettled();
graph.zoomToFit();

// Wait before taking a screenshot
await graph.setLayout('circular');
await graph.waitForSettled();
const screenshot = await graph.captureScreenshot();

// Chain operations with settle
await graph.runAlgorithm('graphty', 'pagerank');
await graph.waitForSettled();
console.log('Algorithm complete, results available');

worldToScreen()

worldToScreen(worldPos): object

x: number

y

y: number

zoomToFit()

zoomToFit(): void

Defined in: src/Graph.ts:1529

Zoom the camera to fit all nodes in view.

Returns

void

Remarks

This operation executes immediately and does not go through the operation queue. It may race with queued camera updates.

For better coordination, consider using batchOperations.

Since

1.0.0

See

waitForSettled to wait for layout before zooming
setCameraState for manual camera control

Example

typescript

// Zoom to fit after data loads
await graph.addNodes(nodes);
await graph.waitForSettled();
graph.zoomToFit();

// Zoom to fit within batch operations
await graph.batchOperations(async () => {
    await graph.setStyleTemplate({graph: {twoD: true}});
    graph.zoomToFit(); // Will execute after style change
});

Algorithm

Classes

Interfaces

DataSource

Classes

Interfaces

LayoutEngine

Classes

Interfaces

Type Aliases

Variables

Class: Graph ​

Implements ​

Constructors ​

Constructor ​

Parameters ​

element ​

useMockInput ​

Returns ​

Properties ​

camera ​

canvas ​

element ​

enableDetailedProfiling? ​

engine ​

eventManager ​

fetchEdges? ​

fetchNodes? ​

initialized ​

needRays ​

operationQueue ​

pinOnDrag? ​

runAlgorithmsOnLoad ​

scene ​

skybox? ​

styles ​

xrHelper ​

Accessors ​

input ​

Get Signature ​

Returns ​

Methods ​

addDataFromSource() ​

Parameters ​

type ​

opts ​

Returns ​

addEdge() ​

Parameters ​

edge ​

srcIdPath? ​

dstIdPath? ​

options? ​

Returns ​

addEdges() ​

Parameters ​

edges ​

srcIdPath? ​

dstIdPath? ​

options? ​

Returns ​

Remarks ​

Since ​

See ​

Example ​

addListener() ​

Parameters ​

type ​

cb ​

Returns ​

addNode() ​

Parameters ​

node ​

idPath? ​

options? ​

Returns ​

addNodes() ​

Parameters ​

nodes ​

idPath? ​

Class: Graph

Implements

Constructors

Constructor

Parameters

element

useMockInput

Returns

Properties

camera

canvas

element

enableDetailedProfiling?

engine

eventManager

fetchEdges?

fetchNodes?

initialized

needRays

operationQueue

pinOnDrag?

runAlgorithmsOnLoad

scene

skybox?

styles

xrHelper

Accessors

input

Get Signature

Returns

Methods

addDataFromSource()

Parameters

type

opts

Returns

addEdge()

Parameters

edge

srcIdPath?

dstIdPath?

options?

Returns

addEdges()

Parameters

edges

srcIdPath?

dstIdPath?

options?

Returns

Remarks

Since

See

Example

addListener()

Parameters

type

cb

Returns

addNode()

Parameters

node

idPath?

options?

Returns

addNodes()

Parameters

nodes

idPath?

options?

Returns

Remarks

Since

See

Example

aiCommand()

Parameters

input

Returns

Example