3d-force-graph

To use 3d-force-graph, you can import it as a module or include it via a CDN script tag. Once initialized with a DOM element, you can load your graph data using the .graphData() method.

Using ES Modules

import ForceGraph3D from '3d-force-graph';

Using a Script Tag

<script src="//cdn.jsdelivr.net/npm/3d-force-graph"></script>

Initializing the Graph

const myGraph = new ForceGraph3D(document.getElementById('my-element'))
  .graphData(myData);

import ForceGraph3D from '3d-force-graph';

// or using a *script* tag
// <script src="//cdn.jsdelivr.net/npm/3d-force-graph"></script>

const myGraph = new ForceGraph3D(<myDOMElement>)
  .graphData(<myData>);

Manage the viewport and rendering cycle:

• cameraPosition([{x,y,z}], [lookAt], [ms]): Move the camera to specific coordinates. Supports animation over ms duration.
• zoomToFit([ms], [px], [nodeFilterFn]): Automatically move the camera to make all nodes visible. px is padding, nodeFilterFn allows focusing on specific nodes.
• pauseAnimation(): Freezes the rendering cycle and user interaction to save performance.
• resumeAnimation(): Resumes the rendering cycle and user interaction.
• refresh(): Redraws all nodes and links.
• postProcessingComposer(): Access the ThreeJS EffectComposer to add rendering effects.
• lights([array]): Set the list of ThreeJS Light instances in the scene.
• scene(): Access the internal ThreeJS Scene.
• camera(): Access the internal ThreeJS Camera.
• renderer(): Access the internal ThreeJS WebGLRenderer.

Create a new 3D force-directed graph by passing a DOM element and an optional configuration object to the ForceGraph3d constructor.

Available configuration options:

• controlType: Camera control type. Options: trackball (default), orbit, or fly.
• rendererConfig: Object containing parameters for the ThreeJS WebGLRenderer constructor (e.g., { antialias: true, alpha: true }).
• extraRenderers: Array of additional renderer instances (e.g., CSS3DRenderer) to include custom objects.

new ForceGraph3d(<domElement>, { configOptions })

Register callbacks for user events:

• onNodeClick(fn): Triggered on node left-click. Args: (node, event).
• onNodeRightClick(fn): Triggered on node right-click. Args: (node, event).
• onNodeHover(fn): Triggered on mouse over. Args: (node, prevNode).
• onNodeDrag(fn): Triggered repeatedly during node drag. Args: (node, {x,y,z}).
• onNodeDragEnd(fn): Triggered when node drag ends. Args: (node, {x,y,z}).
• onLinkClick(fn): Triggered on link left-click. Args: (link, event).
• onBackgroundClick(fn): Triggered on click in empty space. Args: (event).
• enablePointerInteraction([boolean | fn]): Enables mouse tracking for hover/click/tooltips (default: true).
• enableNodeDrag([boolean]): Enables dragging nodes (only supported on d3 engine).

Perform coordinate transformations and bounding box calculations:

• getGraphBbox([nodeFilterFn]): Returns the current bounding box of nodes as { x: [min, max], y: [min, max], z: [min, max] }.
• graph2ScreenCoords(x, y, z): Translates graph coordinates to viewport {x, y} coordinates.
• screen2GraphCoords(x, y, distance): Translates viewport {x, y} and camera distance to graph {x, y, z} coordinates.

Adjust the physics simulation settings:

• forceEngine([str]): Choose between d3 (default) or ngraph.
• numDimensions([int]): Number of dimensions for simulation (1, 2, or 3).
• dagMode([str]): Apply layout constraints for Directed Acyclic Graphs (e.g., td, bu, lr, rl, zout, zin, radialout, radialin).
• d3Force(str, [fn]): Configure or add internal d3 forces (e.g., 'link', 'charge', 'center').
• d3ReheatSimulation(): Sets alpha to 1 to restart the d3 simulation.
• warmupTicks([int]): Number of layout cycles to run before starting to render.
• cooldownTime([num]): How long (ms) to render before stopping and freezing the layout engine.

Manage the view and rendering state using these methods:

• pauseAnimation(): Pauses the graph animation.
• resumeAnimation(): Resumes the graph animation.
• cameraPosition(position: Partial<Coords>, lookAt?: Coords, transitionMs?: number): Sets the camera position and target.
• zoomToFit(durationMs?: number, padding?: number, nodeFilter?: (node: N) => boolean): Zooms the camera to fit the graph or a filtered subset of nodes.
• controls(): Returns the underlying Three.js controls object.

Define how labels are retrieved for nodes and links using nodeLabel() and linkLabel(). Accessors can be a string (key in the object) or a function that returns the label.

Labels can be a string or an HTMLElement.