React Flow

React Flow (published as @xyflow/react) is the React-focused package inside the xyflow monorepo, a set of open-source libraries for building node-based UIs such as workflow builders, pipeline editors, and interactive diagrams. It ships a controlled <ReactFlow /> component, a zustand-backed store, and a large family of hooks (useNodesState, useEdgesState, useReactFlow, useNodeConnections, and more) that give applications full control over nodes, edges, and the pan/zoom viewport while React Flow handles rendering, dragging, connection logic, and selection out of the box.

The library is built on @xyflow/system, a headless core shared with the sibling Svelte Flow package, so viewport math, drag/resize/handle logic, and layout utilities are framework-agnostic and battle-tested across both ecosystems. It is dual-licensed in spirit: fully usable and MIT-licensed for any project, with an optional React Flow Pro subscription and GitHub Sponsors for teams that want to fund ongoing development, plus a Pro-only template/examples library rather than any gating of the open-source package’s functionality.

What You Get

• A <ReactFlow /> container component plus plugin components (Background, MiniMap, Controls, NodeToolbar, NodeResizer, EdgeToolbar) that compose around it
• A rich hook API (useNodesState, useEdgesState, useReactFlow, useNodeConnections, useHandleConnections, useViewport, useOnSelectionChange, useUpdateNodeInternals, and more) for controlled, imperative graph access
• Fully custom node and edge types with support for multiple handles, custom connection lines, and edge labels rendered via EdgeLabelRenderer/ViewportPortal
• Built-in interactions out of the box: drag-to-move, drag-to-connect, multi-selection, keyboard shortcuts, and smooth pan/zoom powered by @xyflow/system
• TypeScript-first types for Node, Edge, and the full ReactFlowInstance API, so custom node/edge data is type-checked end to end

Common Use Cases

• Visual workflow and automation builders (e.g. n8n-style pipeline editors) where users wire steps together
• Data pipeline, ETL, or dependency-graph visualizers that need draggable, connectable nodes
• No-code/low-code app builders and AI agent flow editors that need a canvas for chaining logic blocks
• Org charts, mind maps, and diagramming tools that need custom-styled nodes and edges
• Internal admin tools that visualize state machines, decision trees, or system architecture diagrams

Under The Hood

Architecture React Flow’s package (packages/react) is organized as container components (src/container/ReactFlow, GraphView, Viewport, ZoomPane, Pane, EdgeRenderer, NodeRenderer) that compose around a central zustand store (src/store/index.ts, ~450 lines) created per-instance via createWithEqualityFn. The store owns node/edge state, viewport state, and derived lookups (nodeLookup, connectionLookup), and delegates viewport math, drag handling, resize handling, and connection logic to the framework-agnostic @xyflow/system package (packages/system/src), which is also consumed by the sibling Svelte Flow package. React-specific concerns — hooks (src/hooks, ~25 files covering useReactFlow, useNodesState, useHandleConnections, etc.), context providers (ReactFlowProvider, BatchProvider, StoreContext), and DOM-facing components (Handle, NodeWrapper, EdgeWrapper) — sit on top of that shared core, giving a clean separation between reusable graph-engine logic and React rendering/hook ergonomics.

Tech Stack Written entirely in TypeScript, React Flow targets React >=17 as a peer dependency (with @types/react/@types/react-dom marked optional) and depends on zustand ^4.4.0 for state management and classcat ^5.0.3 for conditional class names, plus its own workspace-internal @xyflow/system. The monorepo (managed with pnpm workspaces and Turborepo, using Changesets for versioned releases) builds the package with Rollup via a shared @xyflow/rollup-config, producing ESM, UMD, and type-declaration outputs, with a separate PostCSS pipeline compiling src/styles/{base,style}.css into the published dist/base.css and dist/style.css.

Code Quality There are no colocated unit tests inside packages/react/src; correctness is instead validated by an end-to-end Playwright suite (tests/playwright/e2e — nodes, edges, pane, node-toolbar, and props specs) that drives real browser interactions against example apps, plus a Cypress suite under examples/react/cypress. Source files are consistently typed, use extensive JSDoc comments (with @public/@example tags) on public hooks like useReactFlow, and follow a uniform naming convention (use-prefixed hooks, PascalCase components) enforced by a shared @xyflow/eslint-config across the workspace.

API Design The public API centers on a small number of well-documented hooks (useNodesState/useEdgesState mirror React’s own useState idiom for graphs) and a single heavily-typed <ReactFlow /> component whose prop names mirror their corresponding event handlers (onNodesChange, onConnect, onNodeDragStop, etc.), keeping the learning curve shallow for anyone familiar with controlled React components. Getting started requires only two npm-installed pieces (the package and its CSS import) and produces a working, pannable/zoomable graph in under 20 lines, while advanced customization (custom nodes, custom connection lines, imperative viewport control via useReactFlow) is opt-in rather than required upfront.