react-force-graph-2d

react-force-graph-2d renders network graph data as an interactive force-directed layout on an HTML5 canvas, using d3-force-3d for the underlying physics simulation. It’s part of the vasturiano/react-force-graph suite, which also ships 3D (WebGL), VR, and AR variants sharing an identical prop and method API — so switching rendering dimension is a one-line import swap with no prop changes. The component exposes 60+ typed props and methods covering node/link styling, directional link particles and arrows, DAG layout modes, zoom/pan/center control, and custom canvas rendering hooks.

Under the hood it wraps vasturiano’s own force-graph canvas kapsule using react-kapsule to bridge imperative canvas rendering with React’s declarative component lifecycle, exposing imperative methods (zoomToFit, centerAt, emitParticle, screen2GraphCoords) through a component ref. It ships as ESM and UMD builds with bundled TypeScript declarations, so it can be used directly in bundler-based apps or loaded straight from a CDN script tag.

What You Get

• A <ForceGraph2D> React component with 60+ typed props for data, styling, and interaction
• Bundled TypeScript declarations plus ESM and UMD builds usable via bundler or CDN script tag
• Imperative ref methods for zoom, pan, center, and screen/graph coordinate conversion
• An identical prop and method API shared with the 3D/VR/AR sibling packages for easy dimension swapping
• Support for directional link particles, arrows, and fully custom per-node/link canvas rendering

Common Use Cases

• Network/graph dashboards - Engineers building admin tools visualize dependency graphs, service maps, or org charts with a live-updating graphData prop.
• Knowledge graph explorers - Data teams building interactive knowledge-graph or ontology browsers use nodeCanvasObject for custom labels and click handlers to drill into node details.
• Real-time traffic/flow visualization - Ops teams visualize pub/sub or network traffic by animating directional link particles between nodes in real time.
• Interactive DAG/tree explorers - Teams visualizing build pipelines, git commit graphs, or org hierarchies use the six DAG layout modes to render top-down or radial tree structures.

Under The Hood

Architecture react-force-graph-2d is a thin adapter layer rather than a self-contained rendering engine: each sub-package’s index.js (e.g. src/packages/react-force-graph-2d/index.js) calls fromKapsule from react-kapsule against the imperative force-graph canvas kapsule, exposing a curated methodNames allowlist (emitParticle, d3Force, zoomToFit, centerAt, screen2GraphCoords, etc.) as component methods bound to a ref. Prop validation is centralized in the monorepo-root src/forcegraph-proptypes.js and shared across all four sibling packages (2D/3D/VR/AR), so the physics and rendering internals live entirely in the separate force-graph, 3d-force-graph, 3d-force-graph-vr and 3d-force-graph-ar packages this repo depends on — changing the core rendering engine happens upstream, not in this repo.

Tech Stack The package targets any React version via a wide peerDependency ("react": "*"), and ships pure ESM (dist/.mjs) plus a UMD bundle (dist/.min.js, usable directly via CDN script tag) built with Rollup, Babel (for JSX/ES transpilation), and rollup-plugin-dts (for hand-authored TypeScript declaration bundling). Runtime dependencies are minimal and delegate the heavy lifting: force-graph for the canvas rendering/physics kapsule, react-kapsule to bridge it into React’s component lifecycle, and prop-types for runtime prop validation.

Code Quality No test files exist anywhere in the repo, and there is no CI workflow under .github/workflows (only an issue template) — quality assurance appears to rely on manual verification against the extensive example/ gallery rather than automated tests. There is no CONTRIBUTING.md either. Type safety is covered by hand-written TypeScript .d.ts declarations (not inferred from source) alongside prop-types for runtime checks, and all four sibling packages follow an identical, consistent thin-wrapper pattern.

API Design The standout design choice is a byte-for-byte identical prop and method API shared across all four rendering targets (2D canvas, 3D/VR/AR WebGL) — switching a graph from 2D to 3D is a one-line import swap with zero prop changes, documented in a single shared README table that flags per-prop availability across all four variants. Getting started requires only a single required prop (graphData), and an extensive example gallery covers most real-world customization needs, though the large prop surface area means deeper customization (custom canvas rendering, DAG modes) does require reading the full API reference.