@integratorivan/react-flow-smart-edge

Why?

React Flow's built-in edges draw a direct line from source to target, which often means edges cut straight across your nodes. React Flow Smart Edge computes a path that goes around them, so your graphs stay readable even as they grow and as nodes move.

It's a tiny, dependency-light library (just @xyflow/react as a peer) that ships ready-to-use edge components and a low-level API for building your own.

Features

• Grid-based A* / jump-point pathfinding finds a path that never crosses your nodes.
• Five edge styles: smart equivalents of every React Flow edge (bezier, straight, step, smooth-step, and simple-bezier).
• Step edges can draw a small bridge arc where they cross each other, so intersections read cleanly. (new!)
• Floating edges connect to the nearest node border instead of a fixed handle.
• Editable waypoints let you drag control points to reshape a route; each segment still avoids nodes.
• Checkpoints route through fixed points without the editing UI.
• Avoid areas keep edges clear of arbitrary regions (e.g. labels), not just nodes.
• Subflow aware routing works correctly inside React Flow groups/subflows.
• Web Worker batch routing keeps large graphs responsive by routing edges off the main thread. (new!)
• If no path is found, the edge drops back to the native React Flow edge.
• Swap the pathfinding or SVG drawing functions, or build custom edges with getSmartEdge.
• Written in strict TypeScript, with browser-based interaction tests.

Install

npm install @tisoap/react-flow-smart-edge

Requires React Flow v12+ (@xyflow/react).

Quick start

import { ReactFlow } from "@xyflow/react";
import { SmartBezierEdge } from "@tisoap/react-flow-smart-edge";
import "@xyflow/react/dist/style.css";

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

const edges = [{ id: "e21", source: "2", target: "1", type: "smart" }];

const edgeTypes = { smart: SmartBezierEdge };

export function Graph() {
  return (
    <ReactFlow
      defaultNodes={nodes}
      defaultEdges={edges}
      edgeTypes={edgeTypes}
      fitView
    />
  );
}

Edge components

Export	React Flow equivalent
SmartBezierEdge	BezierEdge
SmartStraightEdge	StraightEdge
SmartStepEdge	StepEdge
SmartSmoothStepEdge	SmoothStepEdge
SmartSimpleBezierEdge	SimpleBezierEdge
SmartFloatingEdge	Floating edges example
SmartEditableEdge	Editable edge example
SmartCheckpointEdge	No equivalent

Configure any preset with createSmartEdge, or build custom edges with getSmartEdge:

import { createSmartEdge } from "@tisoap/react-flow-smart-edge";

const edgeTypes = {
  // finer routing grid:
  fineStep: createSmartEdge("step", { gridRatio: 5 }),
};

Circuit-style hops

Give the step variants the hops option and crossing wires bridge over each other like a schematic. The edge on top draws a small arc over the one beneath:

import { createSmartEdge } from "@tisoap/react-flow-smart-edge";

const edgeTypes = {
  hop: createSmartEdge("step", { hops: true }),
  // or smooth-step with rounded corners + bridges:
  smoothHop: createSmartEdge("smoothstep", { hops: { borderRadius: 8 } }),
};

See the hops docs for tuning and a live demo.

Web Worker batch routing

For large graphs, route every edge together on a background Web Worker so pathfinding stays off the main thread and the canvas stays responsive. Wrap your flow in SmartEdgeBatchRoutingProvider and read each edge's path with useSmartEdgeRoute:

import {
  ReactFlow,
  ReactFlowProvider,
  BaseEdge,
  BezierEdge,
} from "@xyflow/react";
import {
  SmartEdgeBatchRoutingProvider,
  useSmartEdgeRoute,
} from "@tisoap/react-flow-smart-edge";

function WorkerEdge(props) {
  const routed = useSmartEdgeRoute(props);
  if (!routed) return <BezierEdge {...props} />;
  return (
    <BaseEdge
      id={props.id}
      path={routed.svgPathString}
      markerEnd={props.markerEnd}
    />
  );
}

const edgeTypes = { worker: WorkerEdge };

function Flow({ nodes, edges }) {
  return (
    <ReactFlowProvider>
      <SmartEdgeBatchRoutingProvider
        nodes={nodes}
        options={{ preset: "bezier" }}
      >
        <ReactFlow nodes={nodes} edges={edges} edgeTypes={edgeTypes} />
      </SmartEdgeBatchRoutingProvider>
    </ReactFlowProvider>
  );
}

It is opt-in and additive: the default edge components are unchanged, and the provider falls back to main-thread routing when Web Workers are unavailable. See the Web Worker batch routing docs.

Documentation

Full documentation: tisoap.github.io/react-flow-smart-edge/docs

Guides, the full API reference, and live interactive demos for every feature.

Interactive Storybook examples are also published on Chromatic.

Support

Development

npm ci
npm run storybook    # demos + tests (port 6006)
npm run docs         # Docusaurus dev server → http://localhost:3000/docs
npm run check        # lint, types, spellcheck
npm run test         # Storybook interaction tests
npm run build-docs   # static docs site → website/build

License

MIT