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).

<p align="center"> <a href="https://vasturiano.github.io/react-force-graph/example/large-graph/"><img width="80%" src="https://vasturiano.github.io/react-force-graph/example/preview.png"></a> </p>

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

• Basic (source)
• Directional arrows (source)
• Directional moving particles (source)
• Auto-colored nodes/links (source)
• AR graph (source)
• 2D Text nodes (source)
• 3D Text nodes (source)
• Image nodes (source)
• HTML in nodes (source)
• Custom 2D node shapes (source)
• Custom 3D/VR node geometries (source)
• Curved lines and self links (source)
• Text in links (source)
• Highlight nodes/links (source)
• Larger graph (source)
• Dynamic data changes (source)
• Click to focus on node (source)
• Click to expand/collapse nodes (source)
• Fix nodes after dragging (source)
• Fit graph to canvas (source)
• Camera automatic orbitting (source)
• Node collision detection (source)
• Emit link particles on demand (source)
• Force-directed tree (DAG mode) (source)
• Bloom Post-Processing Effect (source)

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

or

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: