react-cosmos-diagram

A highly customizable React library for building node-based diagrams and graph UIs. → Live demo

Table of Contents

• Installation
• Features
• Quickstart
• Custom Nodes
• Custom Edges
• Custom Connection Line
• Components
• Hooks
• Utilities
• Props Reference
• TypeScript Generics
• Credits
• License

Installation

npm install react-cosmos-diagram

Import the stylesheet once at your app entry point:

import 'react-cosmos-diagram/styles/style.css';

Peer requirements: React >= 17, React DOM >= 17

Features

• Zoom, pan, drag, multi-select, and keyboard shortcuts supported natively
• Fully customizable nodes, edges, and ports with TypeScript generics
• Nested nodes via parentNode
• Drag-selection box (default key: Shift)
• Auto-panning during node drag and edge connection
• onlyRenderVisibleElements for large-diagram performance
• Background component for grid overlays
• Grid snapping via gridStep

Quickstart

Minimal example

import ReactDiagram, { useNodesState, useEdgesState, addEdge } from 'react-cosmos-diagram';
import 'react-cosmos-diagram/styles/style.css';
import { useCallback } from 'react';
import type { Connection } from 'react-cosmos-diagram';

const initialNodes = [
  { id: '1', position: { x: 100, y: 100 }, data: { label: 'Node 1' } },
  { id: '2', position: { x: 300, y: 100 }, data: { label: 'Node 2' } },
];

const initialEdges = [{ id: 'e1-2', source: '1', target: '2' }];

export default function App() {
  const [nodes, , onNodesChange] = useNodesState(initialNodes);
  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);

  const onConnect = useCallback(
    (params: Connection) => setEdges((eds) => addEdge(params, eds)),
    [],
  );

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ReactDiagram
        nodes={nodes}
        edges={edges}
        onNodesChange={onNodesChange}
        onEdgesChange={onEdgesChange}
        onConnect={onConnect}
      />
    </div>
  );
}

ReactDiagram needs a container with explicit width and height.

Full example with edge reconnection

import { useCallback, useRef } from 'react';

import ReactDiagram, {
  useNodesState,
  useEdgesState,
  addEdge,
  updateEdge,
  Connection,
  Edge,
  MarkerType,
  PortType,
} from 'react-cosmos-diagram';

import 'react-cosmos-diagram/styles/style.css';

const initialNodes = [
  {
    id: '1',
    width: 200,
    height: 100,
    data: { label: 'Node1' },
    position: { x: 100, y: 100 },
  },
  {
    id: '2',
    data: { label: 'Node2' },
    position: { x: 300, y: 50 },
  },
  {
    id: '3',
    data: { label: 'Node3' },
    position: { x: 10, y: 10 },
    parentNode: '1',
  },
  {
    id: '4',
    data: { label: 'Node4' },
    position: { x: 650, y: 100 },
  },
];

const initialEdges = [
  {
    id: 'e-1-2',
    type: 'bezier',
    source: '1',
    target: '2',
    markerStart: { type: MarkerType.Arrow },
  },
  {
    id: 'e-2-3',
    source: '2',
    target: '3',
    markerEnd: { type: MarkerType.Arrow },
    type: 'step',
    label: 'label',
  },
  {
    id: 'e-3-4',
    type: 'step',
    source: '3',
    target: '4',
    markerEnd: { type: MarkerType.Arrow },
  },
];

function Diagram() {
  const edgeConnected = useRef(true);

  const [nodes, , onNodesChange] = useNodesState(initialNodes);
  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);

  const onConnect = useCallback(
    (params: Connection) => setEdges((edges) => addEdge({ ...params }, edges)),
    [],
  );

  const onEdgeUpdateStart = useCallback(() => {
    edgeConnected.current = false;
  }, []);

  const onEdgeUpdateEnd = useCallback(
    (_e: MouseEvent, currentEdge: Edge, _portType: PortType) => {
      if (!edgeConnected.current) {
        setEdges((edges) => edges.filter((edge) => edge.id !== currentEdge.id));
      }
      edgeConnected.current = true;
    },
    [],
  );

  const onEdgeUpdate = useCallback(
    (originEdge: Edge, newConnection: Connection) => {
      edgeConnected.current = true;
      setEdges((edges) => updateEdge(originEdge, newConnection, edges));
    },
    [],
  );

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ReactDiagram
        nodes={nodes}
        edges={edges}
        onNodesChange={onNodesChange}
        onEdgesChange={onEdgesChange}
        onConnect={onConnect}
        onEdgeUpdateStart={onEdgeUpdateStart}
        onEdgeUpdateEnd={onEdgeUpdateEnd}
        onEdgeUpdate={onEdgeUpdate}
      />
    </div>
  );
}

export default Diagram;

Custom Nodes

Use NodeProps<YourNodeType> to get typed props. Place Port components inside to define connection points.

import { memo } from 'react';
import { Port, NodeProps, Node } from 'react-cosmos-diagram';
import { Position } from 'react-cosmos-diagram';

type MyNodeData = { label: string; color?: string };
type MyNode = Node<MyNodeData, 'myNode'>;

function MyNode({ data }: NodeProps<MyNode>) {
  return (
    <div style={{ padding: 10, background: data.color ?? '#fff', border: '1px solid #ccc' }}>
      <Port type="target" position={Position.Top} />
      <div>{data.label}</div>
      <Port type="source" position={Position.Bottom} />
    </div>
  );
}

export default memo(MyNode);

Register custom nodes in nodeTypes (define outside the component to avoid recreation):

import { nodeTypes } from './nodeTypes';

const nodeTypes = { myNode: MyNode };

<ReactDiagram nodes={nodes} nodeTypes={nodeTypes} ... />

Custom Edges

Use EdgeProps<YourEdgeType> along with BaseEdge and getBezierPath:

import { memo } from 'react';
import { BaseEdge, EdgeProps, Edge, getBezierPath } from 'react-cosmos-diagram';
import { Position } from 'react-cosmos-diagram';

type MyEdgeData = { animated?: boolean };
type MyEdge = Edge<MyEdgeData, 'myEdge'>;

function MyEdge({
  id,
  sourceX,
  sourceY,
  targetX,
  targetY,
  sourcePosition = Position.Bottom,
  targetPosition = Position.Top,
  style,
  markerEnd,
}: EdgeProps<MyEdge>) {
  const [path, labelX, labelY, offsetX, offsetY] = getBezierPath({
    sourceX,
    sourceY,
    sourcePosition,
    targetX,
    targetY,
    targetPosition,
  });

  return (
    <BaseEdge
      path={path}
      labelX={labelX}
      labelY={labelY}
      style={style}
      markerEnd={markerEnd}
    />
  );
}

export default memo(MyEdge);

Register in edgeTypes:

const edgeTypes = { myEdge: MyEdge };

<ReactDiagram edges={edges} edgeTypes={edgeTypes} ... />

Custom Connection Line

Provide a ConnectionLineComponent prop to render a custom line while the user is dragging a new connection:

import type { ConnectionLineComponentProps } from 'react-cosmos-diagram';

function CustomConnectionLine({ fromX, fromY, toX, toY }: ConnectionLineComponentProps) {
  return (
    <g>
      <path
        fill="none"
        stroke="#222"
        strokeWidth={2}
        d={`M${fromX},${fromY} C${fromX},${toY} ${toX},${fromY} ${toX},${toY}`}
      />
      <circle cx={toX} cy={toY} r={4} fill="#222" />
    </g>
  );
}

<ReactDiagram ConnectionLineComponent={CustomConnectionLine} ... />

Components

| Component | Description | |---|---| | ReactDiagram | Main diagram canvas. Default export. | | ReactDiagramProvider | Context provider for accessing the store outside the canvas. | | Port | Connection port placed inside a custom node. | | BaseEdge | SVG edge primitive used inside custom edges. | | BezierEdge | Built-in bezier curve edge. | | StepEdge | Built-in right-angle step edge. | | Background | Background grid component. |

Hooks

useNodesState<NodeType>(initialNodes)

const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);

Returns [NodeType[], Dispatch<SetStateAction<NodeType[]>>, OnNodesChange<NodeType>].

useEdgesState<EdgeType>(initialEdges)

const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);

Returns [EdgeType[], Dispatch<SetStateAction<EdgeType[]>>, OnEdgesChange<EdgeType>].

useStore(selector)

Zustand selector hook for reading internal diagram state from within the canvas.

useStoreApi()

Returns { getState, setState, subscribe } — use when you need imperative access to the store, e.g. from event handlers outside the React tree.

Utilities

Edge paths

| Function | Returns | Description | |---|---|---| | getBezierPath(params) | [path, labelX, labelY, offsetX, offsetY] | Bezier SVG path + label position | | getBezierEdgeCenter(params) | [centerX, centerY, offsetX, offsetY] | Center point of a bezier edge | | getStepPath(params) | [path, labelX, labelY, offsetX, offsetY] | Right-angle step path | | getStraightPath(params) | [path, labelX, labelY, offsetX, offsetY] | Straight-line path |

Edge state

| Function | Description | |---|---| | addEdge(connection, edges) | Appends a new edge from a Connection object | | updateEdge(oldEdge, newConnection, edges) | Replaces an edge's source/target with a new connection |

Type guards

| Function | Description | |---|---| | isCoreNode(element) | Returns true if the value is a CoreNode | | isCoreEdge(element) | Returns true if the value is a CoreEdge |

Geometry

| Function | Description | |---|---| | clamp(value, min, max) | Clamps a number between min and max | | rectToBox(rect) | Converts Rect to Box | | boxToRect(box) | Converts Box to Rect |

Props Reference

Data

| Prop | Type | Description | |---|---|---| | nodes | NodeType[] | Array of node objects | | edges | EdgeType[] | Array of edge objects | | nodeTypes | NodeTypes<NodeType> | Map of type name → custom node component | | edgeTypes | EdgeTypes<EdgeType> | Map of type name → custom edge component |

Change Handlers

| Prop | Type | Description | |---|---|---| | onNodesChange | OnNodesChange<NodeType> | Called on node position, selection, dimension, or removal changes | | onEdgesChange | OnEdgesChange<EdgeType> | Called on edge selection or removal changes |

Connection

| Prop | Type | Default | Description | |---|---|---|---| | onConnect | (connection: Connection) => void | — | Called when a new connection is completed | | onConnectStart | OnConnectStart | — | Called when the user starts dragging a connection | | onConnectEnd | OnConnectEnd | — | Called when the connection drag ends | | connectionRadius | number | — | Snap radius around a port for completing a connection | | ConnectionLineComponent | ConnectionLineComponent | — | Custom component for the in-progress connection line |

Node Events

| Prop | Type | |---|---| | onNodeClick | (event: MouseEvent, node: NodeType) => void | | onNodeDoubleClick | (event: MouseEvent, node: NodeType) => void | | onNodeContextMenu | (event: MouseEvent, node: NodeType) => void | | onNodeMouseEnter | (event: MouseEvent, node: NodeType) => void | | onNodeMouseMove | (event: MouseEvent, node: NodeType) => void | | onNodeMouseLeave | (event: MouseEvent, node: NodeType) => void | | onNodeDragStart | NodeDragHandler<NodeType> | | onNodeDrag | NodeDragHandler<NodeType> | | onNodeDragEnd | NodeDragHandler<NodeType> |

Edge Events

| Prop | Type | |---|---| | onEdgeClick | (event: MouseEvent, edge: EdgeType) => void | | onEdgeDoubleClick | EdgeMouseHandler<EdgeType> | | onEdgeContextMenu | EdgeMouseHandler<EdgeType> | | onEdgeMouseEnter | EdgeMouseHandler<EdgeType> | | onEdgeMouseMove | EdgeMouseHandler<EdgeType> | | onEdgeMouseLeave | EdgeMouseHandler<EdgeType> | | onEdgeUpdate | (oldEdge: EdgeType, newConnection: Connection) => void | | onEdgeUpdateStart | (event: MouseEvent, edge: EdgeType, portType: PortType) => void | | onEdgeUpdateEnd | (event: MouseEvent, edge: EdgeType, portType: PortType) => void |

Viewport

| Prop | Type | Default | Description | |---|---|---|---| | defaultViewport | Viewport | { x:0, y:0, zoom:1 } | Initial viewport position and zoom | | minZoom | number | 0.5 | Minimum zoom level | | maxZoom | number | 2 | Maximum zoom level | | translateExtent | CoordinateExtent | — | Restricts how far the viewport can be panned | | nodeExtent | CoordinateExtent | — | Restricts how far nodes can be dragged | | panning | boolean | true | Enable/disable viewport panning |

Behavior

| Prop | Type | Default | Description | |---|---|---|---| | nodesDraggable | boolean | true | Allow nodes to be dragged | | elevateNodesOnSelect | boolean | — | Raise selected nodes above others | | autoPanOnNodeDrag | boolean | true | Auto-pan when dragging a node near the edge | | autoPanOnConnect | boolean | true | Auto-pan when dragging a connection near the edge | | onlyRenderVisibleElements | boolean | false | Skip rendering off-screen nodes and edges | | multiSelectionKeyCode | KeyCode | 'Meta' | Key to hold for multi-select | | dragSelectionKeyCode | KeyCode | 'Shift' | Key to hold for drag-selection box | | noDragClassName | string | 'nodrag' | Elements with this class won't trigger node drag | | noPanClassName | string | 'nopan' | Elements with this class won't trigger panning | | smoothStep | boolean | — | Use smooth corners on step edges | | centerStep | boolean | — | Center the step path between source and target | | gridStep | GridStep | — | Snap nodes to a grid while dragging |

TypeScript Generics

v0.10.0 improved generic inference so that custom Node and Edge types flow through hooks and the ReactDiagram component without manual casting.

import ReactDiagram, {
  useNodesState,
  useEdgesState,
  addEdge,
  Node,
  Edge,
} from 'react-cosmos-diagram';
import { useCallback } from 'react';
import type { Connection } from 'react-cosmos-diagram';

// 1. Define typed Node and Edge
type AppNode = Node<{ label: string; color: string }, 'colored'>;
type AppEdge = Edge<{ weight: number }, 'weighted'>;

const initialNodes: AppNode[] = [
  { id: '1', type: 'colored', position: { x: 0, y: 0 }, data: { label: 'A', color: 'red' } },
  { id: '2', type: 'colored', position: { x: 200, y: 0 }, data: { label: 'B', color: 'blue' } },
];

const initialEdges: AppEdge[] = [
  { id: 'e1-2', source: '1', target: '2', data: { weight: 5 } },
];

export default function TypedDiagram() {
  // 2. Hooks infer AppNode / AppEdge from initial values
  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);

  const onConnect = useCallback(
    (params: Connection) =>
      setEdges((eds) => addEdge({ ...params, data: { weight: 1 } }, eds)),
    [],
  );

  // 3. ReactDiagram<AppNode, AppEdge> is inferred — nodeTypes and event handlers
  //    are fully typed without explicit generics.
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ReactDiagram
        nodes={nodes}
        edges={edges}
        onNodesChange={onNodesChange}
        onEdgesChange={onEdgesChange}
        onConnect={onConnect}
        onNodeClick={(_e, node) => console.log(node.data.color)} // typed!
      />
    </div>
  );
}

Credits

Under the hood, react-cosmos-diagram depends on these great libraries:

• d3-zoom — zoom, pan and drag interactions
• d3-drag — node dragging
• zustand — internal state management

License

React Cosmos Diagram is MIT licensed.