Props
<ForceGraph<TNode, TEdge>> accepts the following props. TNode must extend BaseNode { id: string } and TEdge must extend BaseEdge { id: string; source: string; target: string }.
Drives degree-based collision radius and clustering hub priority.
Text rendered on the midpoint of the edge. An empty string hides the label.
Deep-merged with defaults. See Theme.
Skip Louvain detection and the cluster-aware forces. The rest of the simulation (charge, collision, link spring) is untouched.
Render a live zoom-percentage indicator at the given corner.
Rendered while the canvas lib is dynamic-imported, or when
nodes is empty and isLoading is true.Imperative handle
Grab a ref to drive the graph from outside React state.Clustering
Enabled by default. On eachnodes or edges change, the renderer runs Louvain community detection and feeds the result into the simulation as:
- Variable link distance — intra-community links pull to
theme.cluster.intraLinkDistance(120by default); inter-community bridges pull totheme.cluster.interLinkDistance(280). - Centroid force — every tick each node is nudged toward its community’s centroid at strength
theme.cluster.strength · alpha.
graphology + graphology-communities-louvain add ~60 KB gzipped. Both are bundled into the package — no peer dependency to install.
Data
The package does no fetching. Pull data with whatever you already use (TanStack Query, SWR, RSC, plainfetch) and pass arrays straight in.
TNode must extend BaseNode { id: string }; TEdge must extend BaseEdge { id: string; source: string; target: string }. Carry any domain fields on the node or edge directly.
Sub-path exports
SSR and Next.js
The renderer wrapsreact-force-graph-2d, which is canvas-based and client-only. <ForceGraph> is marked "use client" and dynamic-imports the lib internally, so it’s safe to mount inside Next.js server components — the container renders its loadingState (or nothing) on the server and hydrates on the client.
Don’t import
@crosmos/graph from a server-only module. It needs the browser to actually draw.