React Force Graph

https://vasturiano.github.io/react-force-graph
Admin
React Force Graph provides React bindings for the force-graph suite of components, enabling the...
Tokens:4,673
Snippets:38
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Import React Force Graph components

Source: https://vasturiano.github.io/react-force-graph

Import the necessary components for 2D, 3D, VR, or AR force-directed graphs.

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

--------------------------------

### Interaction Configuration Props

Source: https://vasturiano.github.io/react-force-graph

Configuration properties to control interaction behavior and navigation settings.

```APIDOC
## Interaction Configuration

- **linkHoverPrecision** (number): Controls link label display distance.
- **showPointerCursor** (bool | func): Toggles pointer cursor on hoverable elements.
- **controlType** (string): Camera control type in 3D mode (trackball, orbit, or fly).
- **enableZoomInteraction** (bool): Enables zoom interactions on 2D canvas.
- **enablePanInteraction** (bool): Enables pan interactions on 2D canvas.
- **enableNavigationControls** (bool): Enables trackball navigation controls in 3D mode.
```

--------------------------------

### Include React Force Graph via script tag

Source: https://vasturiano.github.io/react-force-graph

Load the library directly in the browser using script tags.

```html
<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>
```

--------------------------------

### Link Styling Properties

Source: https://vasturiano.github.io/react-force-graph

A collection of properties to configure link visibility, color, width, curvature, and custom rendering modes.

```APIDOC
## Link Styling Properties

### linkVisibility
- **Type**: bool, string, or func
- **Default**: true
- **Description**: Link object accessor function, attribute or a boolean constant for whether to display the link line.

### linkColor
- **Type**: string or func
- **Default**: color
- **Description**: Link object accessor function or attribute for line color.

### linkAutoColorBy
- **Type**: string or func
- **Description**: Link object accessor function or attribute to automatically group colors by. Only affects links without a color attribute.

### linkOpacity
- **Type**: number
- **Default**: 0.2
- **Description**: Line opacity of links, between [0,1].

### linkLineDash
- **Type**: number[], string, or func
- **Description**: Link object accessor function, attribute or number array to determine if a line dash should be applied.

### linkWidth
- **Type**: number, string, or func
- **Default**: 1
- **Description**: Link object accessor function, attribute or a numeric constant for the link line width.

### linkResolution
- **Type**: number
- **Default**: 6
- **Description**: Geometric resolution of each link 3D line, expressed in how many radial segments to divide the cylinder.

### linkCurvature
- **Type**: number, string, or func
- **Default**: 0
- **Description**: Link object accessor function, attribute or a numeric constant for the curvature radius of the link line.

### linkCurveRotation
- **Type**: number, string, or func
- **Default**: 0
- **Description**: Link object accessor function, attribute or a numeric constant for the rotation along the line axis to apply to the curve.

### linkMaterial
- **Type**: Material, string, or func
- **Description**: Link object accessor function or attribute for specifying a custom material to style the graph links with.

### linkCanvasObject
- **Type**: func
- **Description**: Callback function for painting a custom canvas object to represent graph links. Signature: `linkCanvasObject(<link>, <canvas context>, <current global scale>)`.

### linkCanvasObjectMode
- **Type**: string or func
- **Default**: () => 'replace'
- **Description**: Link object accessor function or attribute for the custom drawing mode (replace, before, after).

### linkThreeObject
- **Type**: Object3d, string, or func
- **Description**: Link object accessor function or attribute for generating a custom 3d object to render as graph links.
```

--------------------------------

### Interaction Properties

Source: https://vasturiano.github.io/react-force-graph

Configuration properties to control mouse tracking, node dragging, and custom interaction area painting.

```APIDOC
## Interaction Properties

### enablePointerInteraction
- **Type**: bool
- **Default**: true
- **Description**: Whether to enable mouse tracking events. Activates object hover/click and tooltip labels.

### enableNodeDrag
- **Type**: bool
- **Default**: true
- **Description**: Enables dragging nodes by click-dragging. Requires enablePointerInteraction to be true.

### nodePointerAreaPaint
- **Type**: func
- **Description**: Callback for painting a canvas area to detect node pointer interactions. Signature: `nodePointerAreaPaint(<node>, <color>, <canvas context>, <current global scale>)`.

### linkPointerAreaPaint
- **Type**: func
- **Description**: Callback for painting a canvas area to detect link pointer interactions. Signature: `linkPointerAreaPaint(<link>, <color>, <canvas context>, <current global scale>)`.
```

--------------------------------

### lights

Source: https://vasturiano.github.io/react-force-graph

Getter/setter for the list of lights used in the scene.

```APIDOC
## lights(array)

### Description
Access or update the list of lights in the scene. Each item must be an instance of a ThreeJS Light.
```

--------------------------------

### resumeAnimation()

Source: https://vasturiano.github.io/react-force-graph

Resumes the rendering cycle and re-enables user interaction.

```APIDOC
## resumeAnimation()

### Description
Resumes the rendering cycle of the component, and re-enables the user interaction. This method can be used together with pauseAnimation for performance optimization purposes.
```

--------------------------------

### Utility Methods

Source: https://vasturiano.github.io/react-force-graph

Utility methods for coordinate translation and graph bounding box calculations.

```APIDOC
## Utility Methods

### getGraphBbox
- **Arguments**: `([nodeFilterFn])`
- **Description**: Returns the current bounding box of the nodes as `{ x: [<num>, <num>], y: [<num>, <num>], z: [<num>, <num>] }`. Accepts an optional `nodeFilterFn` to filter nodes.

### screen2GraphCoords
- **Arguments**: `(x, y[, distance])`
- **Description**: Translates viewport coordinates to the graph domain. Returns `{x, y (, z)}`.

### graph2ScreenCoords
- **Arguments**: `(x, y[, z])`
- **Description**: Translates node coordinates to the viewport domain. Returns `{x, y}`.
```

--------------------------------

### Force Engine Methods

Source: https://vasturiano.github.io/react-force-graph

Methods available to interact with and control the force simulation engine directly.

```APIDOC
## Force Engine Methods

### d3Force(string, [func])
Access or reconfigure internal forces in the d3 simulation engine (e.g., 'link', 'charge', 'center').

### d3ReheatSimulation()
Reheats the d3 force simulation engine by resetting the alpha value to 1.
```

--------------------------------

### Container Layout Props

Source: https://vasturiano.github.io/react-force-graph

Configuration props for defining the dimensions and visual settings of the graph container.

```APIDOC
## Container Layout Props

### width
- **Type**: number
- **Default**: < window width >
- **Description**: Canvas width, in px.

### height
- **Type**: number
- **Default**: < window height >
- **Description**: Canvas height, in px.

### backgroundColor
- **Type**: string
- **Default**: 2D - light / 3D - dark
- **Description**: Chart background color.

### showNavInfo
- **Type**: bool
- **Default**: true
- **Description**: Whether to show the navigation controls footer info.

### yOffset
- **Type**: number
- **Default**: 1.5
- **Description**: In AR mode, defines the offset distance above the marker where to place the center coordinates of the graph.

### glScale
- **Type**: number
- **Default**: 200
- **Description**: In AR mode, defines the translation scale between real world distances and WebGL units.

### markerAttrs
- **Type**: object
- **Default**: { preset: 'hiro' }
- **Description**: Set of attributes that define the marker where the AR force directed graph is mounted.
```

--------------------------------

### Interaction Callback Props

Source: https://vasturiano.github.io/react-force-graph

A collection of callback functions for handling user interactions with nodes, links, and the background canvas.

```APIDOC
## Interaction Callbacks

### Node Interactions
- **onNodeClick(node, event)**: Callback for node left-button clicks.
- **onNodeRightClick(node, event)**: Callback for node right-clicks.
- **onNodeHover(node, prevNode)**: Callback for node mouse over events.
- **onNodeDrag(node, translate)**: Callback invoked repeatedly while dragging a node.
- **onNodeDragEnd(node, translate)**: Callback invoked when a node drag interaction ends.

### Link Interactions
- **onLinkClick(link, event)**: Callback for link left-button clicks.
- **onLinkRightClick(link, event)**: Callback for link right-clicks.
- **onLinkHover(link, prevLink)**: Callback for link mouse over events.

### Background Interactions
- **onBackgroundClick(event)**: Callback for clicks on empty space.
- **onBackgroundRightClick(event)**: Callback for right-clicks on empty space.

### Zoom and Navigation
- **onZoom({ k, x, y })**: Callback for zoom/pan events.
- **onZoomEnd({ k, x, y })**: Callback for the end of zoom/pan events.
```

--------------------------------

### Render a Force Graph component

Source: https://vasturiano.github.io/react-force-graph

Basic usage of a force graph component with data input.

```jsx
<ForceGraph3D
  graphData={myData}
/>
```

--------------------------------

### Implement custom particle canvas rendering

Source: https://vasturiano.github.io/react-force-graph

Callback function for drawing custom particles on the canvas context for each frame.

```javascript
linkDirectionalParticleCanvasObject(<x>, <y>, <link>, <canvas context>, <current global scale>)
```

--------------------------------

### Force Engine Configuration Properties

Source: https://vasturiano.github.io/react-force-graph

Configuration properties for the force simulation engine, including DAG modes, d3/ngraph specific settings, and simulation lifecycle controls.

```APIDOC
## Force Engine Configuration Properties

### Description
These properties allow you to configure the behavior of the force simulation engine, including the choice of engine (d3 or ngraph), DAG layout constraints, and simulation cooling parameters.

### Configuration Properties
- **numDimensions** (1, 2, or 3) - Optional - Number of dimensions to run the force simulation on (default: 3).
- **forceEngine** (string) - Optional - The force-simulation engine to use: 'd3' or 'ngraph' (default: 'd3').
- **dagMode** (string) - Optional - Apply layout constraints based on graph directionality (e.g., 'td', 'bu', 'lr', 'rl', 'radialout').
- **dagLevelDistance** (number) - Optional - Distance between different graph depths when dagMode is engaged.
- **dagNodeFilter** (func) - Optional - Accessor function to specify nodes to ignore during DAG layout processing.
- **onDagError** (func) - Optional - Callback invoked if a cycle is encountered during DAG layout processing.
- **d3AlphaMin** (number) - Optional - Simulation alpha min parameter for d3 engine.
- **d3AlphaDecay** (number) - Optional - Simulation intensity decay parameter for d3 engine.
- **d3VelocityDecay** (number) - Optional - Nodes' velocity decay for d3 engine.
- **ngraphPhysics** (object) - Optional - Custom physics configuration for ngraph engine.
- **warmupTicks** (number) - Optional - Number of layout engine cycles to dry-run before rendering.
- **cooldownTicks** (number) - Optional - Number of frames to render before stopping the layout engine.
- **cooldownTime** (number) - Optional - Time in ms to render before stopping the layout engine.
- **onEngineTick** (func) - Optional - Callback invoked at every tick of the simulation.
- **onEngineStop** (func) - Optional - Callback invoked when the simulation engine stops.
```

--------------------------------

### Input JSON Syntax

Source: https://vasturiano.github.io/react-force-graph

Required structure for graph data containing nodes and links.

```json
{
    "nodes": [ 
        { 
          "id": "id1",
          "name": "name1",
          "val": 1 
        },
        {
          "id": "id2",
          "name": "name2",
          "val": 10 
        },
        ...
    ],
    "links": [
        {
            "source": "id1",
            "target": "id2"
        },
        ...
    ]
}
```

--------------------------------

### Define Link Pointer Area Paint Callback

Source: https://vasturiano.github.io/react-force-graph

Signature for the custom painting function used to define the interaction area for links.

```javascript
linkPointerAreaPaint(<link>, <color>, <canvas context>, <current global scale>)
```

--------------------------------

### Data Input Props

Source: https://vasturiano.github.io/react-force-graph

Configuration props for defining the graph data structure and node/link accessors.

```APIDOC
## Data Input Props

### graphData
- **Type**: object
- **Default**: { nodes: [], links: [] }
- **Description**: Graph data structure. Can also be used to apply incremental updates.

### nodeId
- **Type**: string
- **Default**: id
- **Description**: Node object accessor attribute for unique node id.

### linkSource
- **Type**: string
- **Default**: source
- **Description**: Link object accessor attribute referring to id of source node.

### linkTarget
- **Type**: string
- **Default**: target
- **Description**: Link object accessor attribute referring to id of target node.
```

--------------------------------

### centerAt(x, y, ms)

Source: https://vasturiano.github.io/react-force-graph

Sets the coordinates of the center of the viewport, allowing for programmatic panning.

```APIDOC
## centerAt(x, y, ms)

### Description
Set the coordinates of the center of the viewport. This method can be used to perform panning on the 2D canvas programmatically.

### Parameters
- **x** (number) - Optional - X coordinate
- **y** (number) - Optional - Y coordinate
- **ms** (number) - Optional - Duration of the transition in milliseconds
```

--------------------------------

### Define Node Pointer Area Paint Callback

Source: https://vasturiano.github.io/react-force-graph

Signature for the custom painting function used to define the interaction area for nodes.

```javascript
nodePointerAreaPaint(<node>, <color>, <canvas context>, <current global scale>)
```

--------------------------------

### scene, camera, renderer, postProcessingComposer, controls

Source: https://vasturiano.github.io/react-force-graph

Accessors for internal ThreeJS objects and the post-processing composer.

```APIDOC
## Accessors

- **scene**: Access the internal ThreeJS Scene.
- **camera**: Access the internal ThreeJS Camera.
- **renderer**: Access the internal ThreeJS WebGL renderer.
- **postProcessingComposer**: Access the post-processing composer to add rendering effects.
- **controls**: Access the internal ThreeJS controls object.
```

--------------------------------

### emitParticle(link)

Source: https://vasturiano.github.io/react-force-graph

Generates a non-cyclical single particle within a specific link. The particle inherits styling from regular particle props.

```APIDOC
## emitParticle(link)

### Description
An alternative mechanism for generating particles, this method emits a non-cyclical single particle within a specific link. The emitted particle shares the styling (speed, shape, color) of the regular particle props.

### Parameters
- **link** (object) - Required - A valid link object included in graphData.
```

--------------------------------

### zoomToFit(ms, px, nodeFilterFn)

Source: https://vasturiano.github.io/react-force-graph

Automatically zooms and pans the canvas so that all nodes fit within the view.

```APIDOC
## zoomToFit(ms, px, nodeFilterFn)

### Description
Automatically zooms/pans the canvas so that all of the nodes fit inside it.

### Parameters
- **ms** (number) - Optional - Duration of the transition in milliseconds
- **px** (number) - Optional - Padding in pixels between the edge of the canvas and the outermost node
- **nodeFilterFn** (function) - Optional - A filter function (node => boolean) to select nodes to include
```

--------------------------------

### Link Styling Properties

Source: https://vasturiano.github.io/react-force-graph

Properties used to define the visual representation of links in the graph.

```APIDOC
## Link Styling Properties

### Description
These properties allow customization of link labels and descriptions.

### Properties
- **linkLabel** (string, func) - Accessor for link name/label.
- **linkDesc** (string, func) - Accessor for link description (VR only).
```

--------------------------------

### cameraPosition

Source: https://vasturiano.github.io/react-force-graph

Re-position the camera using x, y, z coordinates, an optional lookAt target, and an optional transition duration.

```APIDOC
## cameraPosition(position, lookAt, ms)

### Description
Re-position the camera in 3D space. Coordinates are optional, and the camera can be animated over a specified duration.

### Parameters
- **position** ({x, y, z}) - Optional - The target coordinates for the camera.
- **lookAt** ({x, y, z}) - Optional - The point in 3D space the camera should aim at.
- **ms** (number) - Optional - The duration of the transition in milliseconds. Defaults to 0 (immediate).
```

--------------------------------

### refresh

Source: https://vasturiano.github.io/react-force-graph

Triggers a redraw of all nodes and links.

```APIDOC
## refresh()

### Description
Forces a redraw of all nodes and links currently in the graph.
```

--------------------------------

### Define link position update logic

Source: https://vasturiano.github.io/react-force-graph

Custom function to override or supplement the default link position update logic during render iterations.

```javascript
linkPositionUpdate(linkObject, { start, end }, link)
```

--------------------------------

### Node Styling Properties

Source: https://vasturiano.github.io/react-force-graph

Properties used to define the visual representation and behavior of nodes in the graph.

```APIDOC
## Node Styling Properties

### Description
These properties allow customization of node size, color, visibility, and custom rendering logic for 2D, 3D, VR, and AR environments.

### Properties
- **nodeRelSize** (number) - Ratio of node circle area or sphere volume per value unit.
- **nodeVal** (number, string, func) - Accessor for the node numeric value affecting size.
- **nodeLabel** (string, func) - Accessor for the node name/label.
- **nodeDesc** (string, func) - Accessor for node description (VR only).
- **nodeVisibility** (bool, string, func) - Accessor for whether to display the node.
- **nodeColor** (string, func) - Accessor for node color.
- **nodeAutoColorBy** (string, func) - Accessor to automatically group colors.
- **nodeOpacity** (number) - Node sphere opacity [0,1].
- **nodeResolution** (number) - Geometric resolution for 3D spheres.
- **nodeCanvasObject** (func) - Callback for custom 2D canvas rendering.
- **nodeCanvasObjectMode** (string, func) - Defines how to combine custom canvas rendering with default painting.
- **nodeThreeObject** (Object3d, string, func) - Accessor for custom 3D objects.
- **nodeThreeObjectExtend** (bool, string, func) - Whether to extend or replace the default 3D object.
- **nodePositionUpdate** (func) - Custom function for updating node positions.
```

--------------------------------

### zoom(number, ms)

Source: https://vasturiano.github.io/react-force-graph

Sets the 2D canvas zoom amount.

```APIDOC
## zoom(number, ms)

### Description
Set the 2D canvas zoom amount. The zoom is defined in terms of the scale transform of each px.

### Parameters
- **number** (number) - Optional - Zoom scale value
- **ms** (number) - Optional - Duration of the transition in milliseconds
```

--------------------------------

### pauseAnimation()

Source: https://vasturiano.github.io/react-force-graph

Pauses the rendering cycle of the component, freezing the view and cancelling user interaction.

```APIDOC
## pauseAnimation()

### Description
Pauses the rendering cycle of the component, effectively freezing the current view and cancelling all user interaction. This method can be used to save performance in circumstances when a static image is sufficient.
```

--------------------------------

### Define Node Filter Function

Source: https://vasturiano.github.io/react-force-graph

Signature for the optional filter function used in bounding box calculations.

```javascript
node => <boolean>
```
Tokens:
Raw