import '@xyflow/react/dist/style.css';

If consuming raw source instead of the npm package, point to src/react-flow/styles/ and include the CSS via your bundler.

Public API

ReactFlow

import ReactFlow from './container/ReactFlow';

// Core props (simplified)
type ReactFlowProps<NodeType, EdgeType> = {
  nodes: NodeType[];
  edges: EdgeType[];
  onNodesChange?: (changes: NodeChange[]) => void;
  onEdgesChange?: (changes: EdgeChange[]) => void;
  onConnect?: (connection: Connection) => void;
  fitView?: boolean;
  nodeTypes?: Record<string, ComponentType>;
  edgeTypes?: Record<string, ComponentType>;
};

The root component. Mount it inside a sized container (explicit width/height or 100%). Pass controlled nodes and edges arrays and wire up change handlers with useNodesState/useEdgesState.

useReactFlow

import { useReactFlow } from './hooks/useReactFlow';

function useReactFlow<NodeType, EdgeType>(): {
  getNodes(): NodeType[];
  getEdges(): EdgeType[];
  setNodes(nodes: NodeType[]): void;
  setEdges(edges: EdgeType[]): void;
  fitView(options?: FitViewOptions): void;
  zoomIn(): void;
  zoomOut(): void;
  getZoom(): number;
  // ...additional methods
};

Use inside any component rendered under ReactFlow or ReactFlowProvider to programmatically read or mutate graph state without prop drilling.

useNodesState / useEdgesState

import { useNodesState, useEdgesState } from './hooks/useNodesEdgesState';

function useNodesState<T>(initialNodes: Node<T>[]): [Node<T>[], Dispatch<SetStateAction<Node<T>[]>>, (changes: NodeChange[]) => void];
function useEdgesState<T>(initialEdges: Edge<T>[]): [Edge<T>[], Dispatch<SetStateAction<Edge<T>[]>>, (changes: EdgeChange[]) => void];

Convenience hooks that own local node/edge state and return a compatible onNodesChange/onEdgesChange handler. Pass the three return values directly to ReactFlow. Use when you do not need an external state manager.

applyNodeChanges / applyEdgeChanges

import { applyNodeChanges, applyEdgeChanges } from './utils/changes';

function applyNodeChanges(changes: NodeChange[], nodes: Node[]): Node[];
function applyEdgeChanges(changes: EdgeChange[], edges: Edge[]): Edge[];

Pure functions for manually applying change events to node/edge arrays. Use inside a Redux reducer, Zustand action, or any custom state layer as a drop-in replacement for the built-in useNodesState handler.

Background

import { Background, BackgroundVariant, type BackgroundProps } from './additional-components/Background';

// BackgroundVariant enum
enum BackgroundVariant { Dots = 'dots', Lines = 'lines', Cross = 'cross' }

Renders a tiled SVG background pattern inside the canvas. Place it as a child of ReactFlow.

Working examples

Scenario - Minimal controlled flow

A basic two-node, one-edge diagram with built-in state management.

import React, { useCallback } from 'react';
import ReactFlow, { useNodesState, useEdgesState, addEdge, Background, Controls } from './index';
import type { Connection } from './types';
import '@xyflow/react/dist/style.css';

const init_nodes = [
  { id: '1', position: { x: 0, y: 0 }, data: { label: 'Node 1' } },
  { id: '2', position: { x: 0, y: 120 }, data: { label: 'Node 2' } },
];
const init_edges = [{ id: 'e1-2', source: '1', target: '2' }];

export default function MinimalFlow() {
  const [nodes, setNodes, onNodesChange] = useNodesState(init_nodes);
  const [edges, setEdges, onEdgesChange] = useEdgesState(init_edges);

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

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ReactFlow
        nodes={nodes}
        edges={edges}
        onNodesChange={onNodesChange}
        onEdgesChange={onEdgesChange}
        onConnect={onConnect}
        fitView
      >
        <Background variant={BackgroundVariant.Dots} />
        <Controls />
      </ReactFlow>
    </div>
  );
}

Scenario - Programmatic viewport control with useReactFlow

Fit the view or zoom to a specific node on button click from a panel inside the canvas.

import React from 'react';
import ReactFlow, { Panel, useReactFlow, useNodesState, useEdgesState } from './index';

function ControlPanel() {
  const { fitView, zoomIn, zoomOut, getZoom } = useReactFlow();
  return (
    <Panel position="top-right">
      <button onClick={() => fitView({ duration: 400 })}>Fit View</button>
      <button onClick={() => zoomIn({ duration: 200 })}>+</button>
      <button onClick={() => zoomOut({ duration: 200 })}>-</button>
      <span>Zoom: {getZoom().toFixed(2)}</span>
    </Panel>
  );
}

export default function ProgrammaticFlow() {
  const [nodes, , onNodesChange] = useNodesState([
    { id: 'a', position: { x: 100, y: 100 }, data: { label: 'A' } },
  ]);
  const [edges, , onEdgesChange] = useEdgesState([]);

  return (
    <div style={{ width: 800, height: 600 }}>
      <ReactFlow nodes={nodes} edges={edges} onNodesChange={onNodesChange} onEdgesChange={onEdgesChange}>
        <ControlPanel />
      </ReactFlow>
    </div>
  );
}

Scenario - External state with applyNodeChanges

Integrate flow changes into a Zustand store outside React Flow's own state system.

import { create } from 'zustand';
import { applyNodeChanges, applyEdgeChanges } from './utils/changes';
import type { Node, Edge, NodeChange, EdgeChange } from './types';

interface FlowStore {
  nodes: Node[];
  edges: Edge[];
  onNodesChange: (changes: NodeChange[]) => void;
  onEdgesChange: (changes: EdgeChange[]) => void;
}

export const useFlowStore = create<FlowStore>((set) => ({
  nodes: [{ id: '1', position: { x: 50, y: 50 }, data: { label: 'Start' } }],
  edges: [],
  onNodesChange: (changes) =>
    set((state) => ({ nodes: applyNodeChanges(changes, state.nodes) })),
  onEdgesChange: (changes) =>
    set((state) => ({ edges: applyEdgeChanges(changes, state.edges) })),
}));

File walkthrough

• container/ - Mounts the SVG/HTML canvas, wires the Zustand store, composes all internal sub-renderers.
• components/ - Individual rendering units: EdgeWrapper, NodeWrapper, Handle, ConnectionLine, Panel, UserSelection, NodesSelection, EdgeLabelRenderer, ViewportPortal, BatchProvider, StoreUpdater, SelectionListener, ReactFlowProvider, A11yDescriptions, Attribution.
• additional-components/ - Optional UI overlays bundled separately: Background patterns, zoom/fit Controls, MiniMap, NodeResizer, NodeToolbar, EdgeToolbar.
• hooks/ - Public React hooks that subscribe to the Zustand store: useReactFlow, useNodes, useEdges, useViewport, useKeyPress, useStore, useHandleConnections, useNodesData, useConnection, etc.
• store/ - Zustand store factory, selectors, and action creators used internally.
• contexts/ - React contexts, notably NodeIdContext (exposes the current node's id to child components).
• types/ - All exported TypeScript interfaces and types (Node, Edge, Connection, Viewport, change event types, etc.).
• utils/ - Pure utility functions: applyNodeChanges, applyEdgeChanges, isNode, isEdge, path calculators.
• styles/ - Base stylesheet that must be loaded for correct layout.
• index.ts - Single barrel file re-exporting the entire public API.
• custom.d.ts - Ambient module declarations for non-TS assets.

Common pitfalls and fixes

• Unsized container: ReactFlow renders at 0x0 if the parent has no explicit size. Fix: give the wrapper width: 100%; height: 100vh (or any non-zero dimensions).
• Missing stylesheet: Nodes and edges appear misaligned or invisible without the base CSS. Fix: import '@xyflow/react/dist/style.css' exactly once at app root.
• useReactFlow outside provider: Calling the hook outside a ReactFlow tree throws. Fix: wrap the subtree in <ReactFlowProvider> when access is needed above the canvas.
• Stale node positions after programmatic update: Forgetting to call updateNodeInternals after changing a node's handle count causes misaligned edges. Fix: call useUpdateNodeInternals with the affected node id after the change.
• ESM/CJS interop in Jest/Vitest: The package ships ESM; older Jest configs fail to transform it. Fix: add @xyflow/react to transformIgnorePatterns exclusions and enable ESM mode in Jest config.
• addEdge not imported: It is a system-level re-export from @xyflow/system, not directly in this source tree. Fix: import it from the npm package @xyflow/react or add the system package and re-export it alongside this source.

Vibe-coding prompt template

I have a copy of the React Flow source in `src/react-flow/` and a USAGE.md
explaining its API. The upstream package is `@xyflow/react` (xyflow monorepo).

Please integrate React Flow into my project step-by-step:

1. Read `USAGE.md` and `src/react-flow/index.ts` for the full export surface.
2. Install all required peer dependencies listed in USAGE.md.
3. Import the base stylesheet once at my app entry point.
4. Create a new component at `src/components/FlowCanvas.tsx` that:
   - Uses `useNodesState` and `useEdgesState` for controlled state.
   - Renders `<ReactFlow>` inside a full-screen div.
   - Includes `<Background>`, `<Controls>`, and `<MiniMap>` as children.
   - Exposes an `onConnect` callback using `addEdge`.
5. Wrap the relevant part of my app with `<ReactFlowProvider>` where needed.
6. Show me where to call `applyNodeChanges` / `applyEdgeChanges` if I want
   to move state into my existing Zustand store.
7. Point out any tsconfig or bundler changes required.

Use only exports visible in `src/react-flow/index.ts`. Do not invent APIs.

License and credit

React Flow is released under the MIT License. See source/LICENSE if present, or the upstream repository at https://github.com/xyflow/xyflow. The npm package is published as @xyflow/react. Commercial use inside revenue-generating products is permitted under MIT but the authors request sponsorship via React Flow Pro or GitHub Sponsors.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.