React Flow

Common errors

• Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause React Flow hooks like `useNodesState` or `useEdgesState` are being called outside of a functional React component, or there are multiple instances of React loaded.
  fix Ensure all React Flow hooks are called within the top level of a functional React component. If using multiple React versions, ensure your bundler resolves to a single React instance.

• TypeError: Cannot read properties of undefined (reading 'x') (or similar rendering issues like nodes overlapping/not appearing)

  cause The `ReactFlow` component's container does not have explicit `width` and `height` CSS properties, or the `reactflow/dist/style.css` stylesheet is not imported.
  fix Provide a defined `width` and `height` to the `div` wrapper around your `ReactFlow` component (e.g., `style={{ width: '100vw', height: '100vh' }}`). Additionally, verify that `import 'reactflow/dist/style.css';` is present in your application.

• Minimap is not defined / Controls is not defined / Background is not defined

  cause One of the optional UI components (MiniMap, Controls, Background) is used but not imported from `reactflow`.
  fix Ensure all desired components are explicitly imported using named imports: `import { MiniMap, Controls, Background } from 'reactflow';`

Warnings

• breaking The `reactflow` package (v11) is being succeeded by `@xyflow/react` (v12). This transition involves a package name change and significant API updates. Users of `reactflow` should plan for a migration when moving to v12.
  Fix: For new projects, consider installing `@xyflow/react` to use the latest v12 features. For existing v11 projects, refer to the `@xyflow/react` migration guide for detailed instructions on upgrading and adapting to the new API and package name.
• gotcha Forgetting to import the `reactflow/dist/style.css` stylesheet will result in an unstyled and potentially non-functional React Flow canvas, as essential layout and component styles are missing.
  Fix: Always include `import 'reactflow/dist/style.css';` in your root component or a relevant entry file to ensure proper styling.
• gotcha React Flow requires `react` and `react-dom` as peer dependencies with versions `>=17`. Using older versions of React may lead to compatibility issues or errors.
  Fix: Ensure your project's `react` and `react-dom` versions are `17.0.0` or higher. Update your `package.json` dependencies and reinstall if necessary.
• gotcha When implementing custom nodes or edges, they must be explicitly registered with the `nodeTypes` and `edgeTypes` props on the `ReactFlow` component. Failing to do so will prevent your custom elements from rendering.
  Fix: Pass an object mapping your custom type names to their respective React components via the `nodeTypes` or `edgeTypes` prop: `<ReactFlow nodeTypes={nodeTypes} ... />`.

Install

• npm install reactflow npm
• yarn add reactflow yarn
• pnpm add reactflow pnpm

Imports

• ReactFlow
  wrong:

  import { ReactFlow } from 'reactflow';

  correct:

  import ReactFlow from 'reactflow';

  ReactFlow is the default export of the library, not a named export. Ensure you are importing the default component for the main canvas.
• useNodesState
  wrong:

  import useNodesState from 'reactflow';

  correct:

  import { useNodesState } from 'reactflow';

  Hooks like useNodesState, useEdgesState, and utilities like addEdge are named exports.
• MiniMap
  wrong:

  import MiniMap from 'reactflow';

  correct:

  import { MiniMap, Controls, Background } from 'reactflow';

  Helper components such as MiniMap, Controls, and Background are named exports.
• StyleSheet
  wrong:

  import 'reactflow/style.css';

  correct:

  import 'reactflow/dist/style.css';

  The core stylesheet is crucial for proper rendering and requires a direct import path to the `dist` folder.

Quickstart

This quickstart demonstrates a basic React Flow setup with initial nodes and edges, enabling drag, zoom, pan, and interactive connecting. It includes `MiniMap`, `Controls`, and `Background` components for enhanced user experience.

import { useCallback } from 'react';
import ReactFlow, {
  MiniMap,
  Controls,
  Background,
  useNodesState,
  useEdgesState,
  addEdge,
} from 'reactflow';

import 'reactflow/dist/style.css';

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

const initialEdges = [
  { id: 'e1-2', source: '1', target: '2', label: 'to the next' },
  { id: 'e2-3', source: '2', target: '3', animated: true },
];

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

  const onConnect = useCallback((params) => 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
      >
        <MiniMap />
        <Controls />
        <Background variant="dots" gap={12} size={1} />
      </ReactFlow>
    </div>
  );
}

export default Flow;