Skip to main content

Quick Start

In five minutes you'll have an interactive, draggable graph rendered with your own React components. Make sure you've installed the package first.

1. Describe your network​

A graph is just two arrays: nodes and links. Nodes need an id, and can carry any extra data you like. Links connect nodes by their position in the nodes array:

data.ts
export const team = {
  nodes: [
    { id: 1, name: "Ava", role: "Lead" },
    { id: 2, name: "Liam", role: "Frontend" },
    { id: 3, name: "Mia", role: "Design" },
    { id: 4, name: "Noah", role: "Backend" },
  ],
  links: [
    { source: 0, target: 1 }, // Ava — Liam
    { source: 0, target: 2 }, // Ava — Mia
    { source: 0, target: 3 }, // Ava — Noah
  ],
};
Links use array indices, not ids

source and target refer to indices in the nodes array (0 = first node), not to the node's id field. If your data is id-based, map it to indices first — see the graph prop for a one-liner that does it.

2. Render the graph​

Drop the Graph component inside a container that has a height — the graph fills its parent, so a zero-height parent means an invisible graph:

TeamGraph.tsx
import { Graph } from "d3-graph-react";
import { team } from "./data";

export const TeamGraph = () => (
  <div style={{ height: 500, display: "flex" }}>
    <Graph
      graph={team}
      chargeForce={{ strength: -250 }}
      linkForce={{ length: 130, strength: 1 }}
      gravityForce={{ strength: 0.06, center_x: 250, center_y: 250 }}
    />
  </div>
);
Always configure some forces

A force is only added to the simulation when you pass its prop. With no forces at all, nodes have nothing pulling them apart and pile up in a corner. The trio above — negative charge to spread nodes, link force to hold neighbors together, gravity to keep everything centered — is a great starting point for almost any graph.

3. Make the nodes yours​

By default nodes render as plain white boxes. Pass a NodeComponent to render anything you want — it's a regular React component receiving the node's data, fully typed:

TeamGraph.tsx
export const TeamGraph = () => (
  <div style={{ height: 500, display: "flex" }}>
    <Graph
      graph={team}
      chargeForce={{ strength: -250 }}
      linkForce={{ length: 130, strength: 1 }}
      gravityForce={{ strength: 0.06, center_x: 250, center_y: 250 }}
      NodeComponent={({ node }) => (
        <div className="member-card">
          <strong>{node.name}</strong>
          <small>{node.role}</small>
        </div>
      )}
    />
  </div>
);

Here's that pattern live — drag the cards around:

NodeComponent={PersonCard}Live

4. Tune the feel​

Every aspect of the physics is a prop. Some favorites to play with:

What you wantProp to reach for
More space between nodeschargeForce — more negative
Shorter/longer connectionslinkForce — length
Keep the graph centeredgravityForce
A graph that never stops movingambientAlphaTarget
Limit how far users can zoomzoomScale
Custom link stylingLinkComponent

Or skip the reading and head straight to the Playground to tweak everything with sliders on real datasets.

Full example​

TeamGraph.tsx
import { Graph } from "d3-graph-react";

const team = {
  nodes: [
    { id: 1, name: "Ava", role: "Lead" },
    { id: 2, name: "Liam", role: "Frontend" },
    { id: 3, name: "Mia", role: "Design" },
    { id: 4, name: "Noah", role: "Backend" },
  ],
  links: [
    { source: 0, target: 1 },
    { source: 0, target: 2 },
    { source: 0, target: 3 },
  ],
};

export const TeamGraph = () => (
  <div style={{ height: 500, display: "flex" }}>
    <Graph
      graph={team}
      chargeForce={{ strength: -250 }}
      linkForce={{ length: 130, strength: 1 }}
      gravityForce={{ strength: 0.06, center_x: 250, center_y: 250 }}
      ambientAlphaTarget={0.03}
      NodeComponent={({ node }) => (
        <div className="member-card">
          <strong>{node.name}</strong>
          <small>{node.role}</small>
        </div>
      )}
    />
  </div>
);

Next steps​