React Sigma

Before using React Sigma, ensure you have knowledge of the following:

1. React: You should have an existing React project setup.
2. Sigma: React Sigma is a React wrapper for Sigma.js. It is not a replacement for Sigma's documentation; you should refer to Sigma's official docs for graph rendering logic and core Sigma concepts.
3. Graphology: Since React Sigma relies on graphology for graph data structures, familiarity with it is recommended.

Regular layouts are intended for one-time execution (e.g., random or circular). The layout hooks return two functions:

• positions: Executes the layout on the sigma graph and returns a map of positions (where the key is the node key) without modifying the graph itself.
• assign: Executes the layout on the sigma graph and directly saves the node positions into the graph.

Example usage:

const { positions, assign } = useLayoutCircular(...);

The SigmaContainer follows a specific lifecycle to bridge React and Sigma:

1. DOM Rendering: It renders a container structure containing a <div className="sigma-container"> element.
2. Instantiation: It instantiates a new Sigma instance targeting that div and stores it in a React context.
3. Child Rendering: It renders all child components.
4. Interaction: Child components consume the Sigma instance via context to manipulate the graph or the view.

Warning: Changing props on SigmaContainer triggers a re-render of the container and all its children, causing the Sigma instance to be killed and re-created.

You can pass a pre-instantiated graphology instance directly to the graph prop of SigmaContainer.

Warning: When passing an instance, Sigma will be killed, recreated, and the graph will be reloaded on every render of the component. To avoid significant performance issues, especially with large graphs, you must manage the React lifecycle of the parent component to ensure the instance is stable and not recreated on every render.

import Graph from "graphology";
import { SigmaContainer, useLoadGraph } from "@react-sigma/core";
import "@react-sigma/core/lib/style.css";

export const DisplayGraph = () => {
  const graph = new Graph();
  graph.addNode("first", { x: 0, y: 0, size: 15, label: "My first node", color: "#FA4F40" });
  return <SigmaContainer style={{ height: "500px", width: "500px" }} graph={graph}></SigmaContainer>;
};

Non-iterative layouts (such as random or circular) are computed once to determine node positions. The layout modules for these types export a hook that provides two functions:

1. positions(): Returns the computed node positions without modifying the graph.
2. assign(graph): Computes the positions and immediately assigns them to the provided graph.

These hooks must be used within a component that is a child of SigmaContainer.

You can override the default styles and icons of controls by providing custom JSX children. The required number of children depends on the specific control:

• FullScreenControl: Requires two children: the first for the "enter fullscreen" action and the second for the "exit fullscreen" action.
• ZoomControl: Requires three children: zoom in, zoom out, and zoom reset.
• Worker layout controls: Requires two children: stop and start.

By default, SigmaContainer creates a standard graphology graph when it mounts. If you need to support features like parallel edges (multi-graphs), you must explicitly pass the desired graph constructor to the graph property of SigmaContainer. This step is mandatory for using multi-graphs.

import { MultiGraph } from "graphology";

// Pass the constructor to SigmaContainer to ensure the internal graph is a MultiGraph
<SigmaContainer graph={MultiGraph} />

Worker layouts are designed for continuous or iterative processes (like force atlas 2) that run in a web worker. The worker hooks return control functions and status information:

• start: Starts the layout process.
• stop: Stops the layout process.
• kill: Kills the layout worker.
• isRunning: A boolean indicating whether the layout is currently running.

Example usage:

const { stop, start, kill, isRunning } = useWorkerLayoutForceAtlas2(...);

Iterative layouts (such as forceatlas2) run continuously in a web worker to refine node positions. These modules provide three ways to interact with the layout:

1. Layout Hook: Similar to non-iterative layouts, it runs a fixed number of iterations (configurable via options like { iterations: 100 }).
2. Worker Management Hook: Provides fine-grained control over the background worker via start(), stop(), kill(), and an isRunning status.
3. Control Component: A pre-built UI component that provides start/stop buttons for the user.