reagraph Documentation

Reagraph is a high-performance WebGL-based network graph visualization library for React.

Key Features

• Performance: WebGL-based rendering.
• Node Customization: Sizing based on attributes, page rank, centrality, or custom logic; node badges; customizable nodes.
• Interactivity: Dragging nodes, lasso selection, expand/collapse nodes, radial context menu, and path finding.
• Visuals: Light/Dark mode with custom themes, advanced label placement, edge interpolation/styling, clustering, edge bundling, and highlighting/selection hooks.

Built-in Layouts

Reagraph supports various 2D and 3D layouts, including:

• Force Directed: 2D and 3D
• Tree: Top Down (2D/3D) and Left Right (2D/3D)
• Radial: Radial Out (2D/3D)
• Hierarchical: Top Down (2D) and Left Right (2D)
• Other: Circular 2D, No Overlap 2D, Force Atlas2 2D, Concentric (2D/3D)

To use reagraph in your React project, install the package using your preferred package manager.

npm i reagraph --save
# or
yarn add reagraph

The Edge component allows fine-grained control over how text labels are positioned relative to the edge line and each other.

Label Placement (labelPlacement)

Controls where the main label sits relative to the edge line:

• below: Shows the label under the edge line.
• above: Shows the label above the edge line.
• inline: Shows the label along the edge line.
• natural: Uses normal text positions.

Sub-label Placement (subLabelPlacement)

Controls where the subLabel is positioned relative to the main label:

• below: Shows the sub-label below the main label.
• above: Shows the sub-label above the main label.

The interpolation prop determines the visual path of the edge:

• linear: The edge is drawn as a straight line.
• curved: The edge is drawn as a curved path. This is useful for avoiding overlapping edges or creating more organic graph layouts.

To use the recommended linting rules for this project, import the reaviz-lint-rules configuration package in your eslint.config.ts file. You can extend these rules by spreading the config into your exported array and adding custom rule overrides in the rules object.

Note that the base configuration is provided by the reaviz-lint-rules package.

import config from 'reaviz-lint-rules';

export default [...config, { rules: { 'react/no-unknown-property': 'warn' } }];

To make the selection logic work with your UI, you must pass the returned handlers from useSelection to your graph components:

• onNodeClick: Pass to the component handling node clicks to enable selection via clicking.
• onCanvasClick: Pass to the canvas click handler to allow clicking empty space to deselect.
• onNodePointerOver / onNodePointerOut: Pass to node pointer events to enable hover-based highlighting of adjacent elements.
• onLasso / onLassoEnd: Pass to your lasso/area selection implementation to sync lasso results with the selection state.

The primary way to render a graph is by using the GraphCanvas component. You must provide a nodes array and an edges array.

Each node requires a unique id and can optionally include a label. Each edge requires a unique id, a source node ID, and a target node ID.

import React from 'react';
import { GraphCanvas } from 'reagraph';

export default () => (
  <GraphCanvas
    nodes={[
      {
        id: 'n-1',
        label: '1'
      },
      {
        id: 'n-2',
        label: '2'
      }
    ]}
    edges={[
      {
        id: '1->2',
        source: 'n-1',
        target: 'n-2',
        label: 'Edge 1-2'
      }
    ]}
  />
);

The useCameraControls hook provides access to the graph's camera controls via a React context. It allows you to programmatically control camera movement, zooming, panning, and state (frozen/unfrozen).

Note: This hook must be used within a ControlsProvider component, otherwise it will throw an error: `useCameraControls` hook must be used within a `ControlsProvider` component.

import { useCameraControls } from 'reagraph';

const MyComponent = () => {
  const { zoomIn, resetControls, freeze } = useCameraControls();

  return (
    <div>
      <button onClick={() => zoomIn()}>Zoom In</button>
      <button onClick={() => resetControls(true)}>Reset (Animated)</button>
      <button onClick={() => freeze()}>Freeze Camera</button>
    </div>
  );
};

The GraphCanvas component is the primary entrypoint for rendering a graph in Reagraph. It is a React component that accepts configuration via GraphCanvasProps and can be controlled via a ref of type GraphCanvasRef.

import { GraphCanvas } from 'reagraph';

// Basic usage
const MyGraph = () => (
  <GraphCanvas />
);