react-force-graph

The react-force-graph suite provides React bindings for various force-directed graph visualizations. It exports four standalone packages with identical interfaces, allowing you to choose the rendering engine that best fits your needs:

• react-force-graph-2d: Uses HTML Canvas for 2D rendering.
• react-force-graph-3d: Uses ThreeJS/WebGL for 3D rendering.
• react-force-graph-vr: Uses A-Frame for Virtual Reality (VR) rendering.
• react-force-graph-ar: Uses AR.js for Augmented Reality (AR) rendering.

All components support zooming, panning, node dragging, and node/link hover or click interactions. They use d3-force-3d as the underlying physics engine.

You can use the components by importing them from their respective NPM packages in your React project, or by including them via a CDN script tag.

Using NPM imports

import ForceGraph2D from 'react-force-graph-2d';
import ForceGraph3D from 'react-force-graph-3d';
import ForceGraphVR from 'react-force-graph-vr';
import ForceGraphAR from 'react-force-graph-ar';

Using Script tags

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

If forceEngine is set to 'd3', you can tune the following parameters:

• d3AlphaMin: Sets the simulation alpha min.
• d3AlphaDecay: Sets the simulation intensity decay.
• d3VelocityDecay: Sets the velocity decay (simulates medium resistance).

For graphs with directionality, you can apply layout constraints using dagMode. This is only effective for DAG structures (no cycles).

• dagMode: Set to 'td' (top-down), 'bu' (bottom-up), 'lr' (left-to-right), 'rl' (right-to-left), 'zout' (near-to-far), 'zin' (far-to-near), 'radialout' (outwards-radially), or 'radialin' (inwards-radially).
• dagLevelDistance: Specifies the distance between different graph depths.
• dagNodeFilter(node => boolean): Specify nodes to ignore during DAG processing. Excluded nodes move freely.
• onDagError(loopNodes): Callback invoked if a cycle is detected. loopNodes is an array of node IDs. By default, this throws an exception.

When using 3D, VR, or AR modes, you can configure the underlying ThreeJS WebGLRenderer or include additional renderers.

• rendererConfig: An object containing configuration parameters for the WebGLRenderer constructor (e.g., { antialias: true, alpha: true }). This only takes effect on component mount.
• extraRenderers: An array of additional renderer instances (e.g., CSS3DRenderer) to include alongside WebGL.

You can choose between different simulation engines and configure their specific parameters:

• forceEngine: Choose between 'd3' (default) or 'ngraph'. Available in 2D, 3D, VR, and AR.
• numDimensions: Number of dimensions for the simulation (1, 2, or 3). Not applicable to 2D mode.
• onEngineTick(func): Callback invoked at every tick of the simulation.
• onEngineStop(func): Callback invoked when the simulation stops and the layout is frozen.
• warmupTicks: Number of dry-run cycles before rendering starts.
• cooldownTicks: Number of frames to render before stopping (default: Infinity).
• cooldownTime: Time in ms to render before stopping (default: 15000ms).

To render a basic 3D graph, import the ForceGraph3D component and pass your graph data to the graphData prop.

<ForceGraph3D
  graphData={myData}
/>

The following methods are available for controlling the 2D canvas view:

• centerAt([x], [y], [ms]): Sets the viewport center coordinates. x and y are optional (allowing 1D motion). The 3rd argument is the animation duration in ms.
• zoom([number], [ms]): Sets the zoom level (scale transform). 1 is unity. The 2nd argument is the animation duration in ms.
• zoomToFit([ms], [px], [nodeFilterFn]): Automatically pans/zooms to fit nodes.
  • ms: Animation duration (default: 0ms).
  • px: Padding between edge and outermost node (default: 10px).
  • nodeFilterFn: A function node => boolean to include only specific nodes in the fit calculation.

To optimize performance, you can manually control the rendering cycle:

• pauseAnimation(): Freezes the current view and cancels user interaction. Useful for static snapshots.
• resumeAnimation(): Resumes the rendering cycle and re-enables interaction.
• refresh(): Forces a redraw of all nodes and links (available in 2D, 3D, VR, and AR).

For 3D, VR, and AR modes, you can manipulate the camera and scene directly via component methods:

• cameraPosition([x, y, z], [lookAt], [ms]): Re-positions the camera. lookAt is an {x, y, z} point the camera should face. ms is the animation duration.
• lights([array]): Getter/setter for the list of ThreeJS Light instances in the scene.
• scene: Access the internal ThreeJS Scene object.
• camera: Access the internal ThreeJS PerspectiveCamera object.
• renderer: Access the internal ThreeJS WebGLRenderer object.
• postProcessingComposer: Access the EffectComposer to add post-processing effects.