react-force-graph

[![NPM package][npm-img]][npm-url] [![NPM Downloads][npm-downloads-img]][npm-downloads-url]

React bindings for the force-graph suite of components: force-graph (2D HTML Canvas), 3d-force-graph (ThreeJS/WebGL), 3d-force-graph-vr (A-Frame) and 3d-force-graph-ar (AR.js).

This module exports 4 React components with identical interfaces: ForceGraph2D, ForceGraph3D, ForceGraphVR and ForceGraphAR. Each can be used to represent a graph data structure in a 2 or 3-dimensional space using a force-directed iterative layout.

For dependency convenience, all of the components are also available as stand-alone packages: react-force-graph-2d, react-force-graph-3d, react-force-graph-vr and react-force-graph-ar.

Uses canvas/WebGL for rendering and d3-force-3d for the underlying physics engine. Supports zooming/panning, node dragging and node/link hover/click interactions.

Examples

Quick start

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';

import { ForceGraph2D, ForceGraph3D, ForceGraphVR, ForceGraphAR } from 'react-force-graph';

or using a script tag

<script src="//unpkg.com/react-force-graph-2d"></script>
<script src="//unpkg.com/react-force-graph-3d"></script>
<script src="//unpkg.com/react-force-graph-vr"></script>
<script src="//unpkg.com/react-force-graph-ar"></script>

then

<ForceGraph3D
  graphData={myData}
/>

API reference

Note that not all props listed below apply to all 4 components. The last 4 columns in these tables indicate the specific component availability of each prop/method.

Data input

Prop	Type	Default	Description	2D	3D	VR	AR
<b>graphData</b>	<i>object</i>	`{ nodes: [], links: [] }`	Graph data structure (see below for syntax details). Can also be used to apply incremental updates.	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>nodeId</b>	<i>string</i>	`id`	Node object accessor attribute for unique node id (used in link objects source/target).	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>linkSource</b>	<i>string</i>	`source`	Link object accessor attribute referring to id of source node.	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>linkTarget</b>	<i>string</i>	`target`	Link object accessor attribute referring to id of target node.	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:

Container layout

Prop	Type	Default	Description	2D	3D	VR	AR
<b>width</b>	<i>number</i>	<window width>	Canvas width, in px.	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>height</b>	<i>number</i>	<window height>	Canvas height, in px.	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>backgroundColor</b>	<i>string</i>	(2D - <i>light</i> / 3D - <i>dark</i>)	Chart background color.	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>showNavInfo</b>	<i>bool</i>	`true`	Whether to show the navigation controls footer info.		:heavy_check_mark:	:heavy_check_mark:
<b>yOffset</b>	<i>number</i>	1.5	In AR mode, defines the offset distance above the marker where to place the center coordinates `<0,0,0>` of the force directed graph. Measured in terms of marker width units.				:heavy_check_mark:
<b>glScale</b>	<i>number</i>	200	In AR mode, defines the translation scale between real world distances and WebGL units, determining the overall size of the graph. Defined in terms of how many GL units fit in a full marker width.				:heavy_check_mark:
<b>markerAttrs</b>	<i>object</i>	`{ preset: 'hiro' }`	Set of attributes that define the marker where the AR force directed graph is mounted, according to the a-marker specification. This prop only has an effect on component mount.				:heavy_check_mark:

Node styling

Prop	Type	Default	Description	2D	3D	VR	AR
<b>nodeRelSize</b>	<i>number</i>	4	Ratio of node circle area (square px) [2D] or sphere volume (cubic px) [3D] per value unit.	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>nodeVal</b>	<i>number</i>, <i>string</i> or <i>func</i>	`val`	Node object accessor function, attribute or a numeric constant for the node numeric value (affects node size).	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>nodeLabel</b>	<i>string</i> or <i>func</i>	`name`	Node object accessor function or attribute for name (shown in label). Supports plain text or HTML content (except in VR).	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>nodeDesc</b>	<i>string</i> or <i>func</i>	`desc`	For VR only. Node object accessor function or attribute for description (shown under label).			:heavy_check_mark:
<b>nodeVisibility</b>	<i>bool</i>, <i>string</i> or <i>func</i>	`true`	Node object accessor function, attribute or a boolean constant for whether to display the node.	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>nodeColor</b>	<i>string</i> or <i>func</i>	`color`	Node object accessor function or attribute for node color.	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>nodeAutoColorBy</b>	<i>string</i> or <i>func</i>		Node object accessor function or attribute to automatically group colors by. Only affects nodes without a color attribute.	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>nodeOpacity</b>	<i>number</i>	0.75	Nodes sphere opacity, between [0,1].		:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>nodeResolution</b>	<i>number</i>	8	Geometric resolution of each node's sphere, expressed in how many slice segments to divide the circumference. Higher values yield smoother spheres. Only applicable to 3D modes.		:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>nodeCanvasObject</b>	<i>func</i>	default 2D node object is a circle, sized according to `val` and styled according to `color`.	Callback function for painting a custom 2D canvas object to represent graph nodes. Should use the provided canvas context attribute to perform drawing operations for each node. The callback function will be called for each node at every frame, and has the signature: `nodeCanvasObject(<node>, <canvas context>, <current global scale>)`.	:heavy_check_mark:
<b>nodeCanvasObjectMode</b>	<i>string</i> or <i>func</i>	`() => 'replace'`	Node object accessor function or attribute for the custom drawing mode. Use in combination with `nodeCanvasObject` to specify how to customize nodes painting. Possible values are: <ul><li>`replace`: the node is rendered using just `nodeCanvasObject`.</li><li>`before`: the node is rendered by invoking `nodeCanvasObject` and then proceeding with the default node painting.</li><li>`after`: `nodeCanvasObject` is applied after the default node painting takes place.</li></ul>Any other value will be ignored and the default drawing will be applied.	:heavy_check_mark:
<b>nodeThreeObject</b>	<i>Object3d</i>, <i>string</i> or <i>func</i>	default 3D node object is a sphere, sized according to `val` and styled according to `color`.	Node object accessor function or attribute for generating a custom 3d object to render as graph nodes. Should return an instance of ThreeJS Object3d. If a <i>falsy</i> value is returned, the default 3d object type will be used instead for that node.		:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
<b>nodeThreeObjectExtend</b>	<i>bool</i>, <i>string</i> or <i>func</i>	`false`	Node object accessor function, attribute or a boolean value for whether to replace the default node when using a custom `nodeThreeObject` (`false`) or to extend it (`true`).		:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:

Link styling

Prop	Type	Default	Description	2D	3D	VR	AR
<b>linkLabel</b>	<i>string</i> or <i>func</i>	`name`	Link object accessor function or attribute for name (shown in label). Supports plain text or HTML content (except in VR).	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark: