Skip to Content
React Flow 13 is here! Read the announcement →
LearnTroubleshootingMigrate to v13

Migrate to React Flow 13

You can find the docs for old versions of React Flow here: v12 , v11 , v10  and v9 .

React Flow 13 is all about performance, and most apps only need a few small changes to upgrade. It requires React 18 and Zustand 5 and no longer ships a UMD build. For a full list of changes, see the release notes .

Overview of the changes:

  1. Requirements: update to React 18 and Zustand 5.
  2. Change handling: onNodesChange and onEdgesChange receive changesets, and the change types were renamed.
  3. Store access: useStore and useStoreApi were replaced by specialized store hooks.
  4. Styling and colorMode: color mode is detected automatically, styles live in a CSS layer and the pane cursor moved to a pseudo-element.
  5. Click and drag thresholds: nodeClickDistance was removed and paneClickDistance is now paneDragThreshold.
  6. Viewport: interrupted animations resolve with false and unitless fitViewOptions.padding values are pixels.
  7. Connections and handles: onConnectEnd uses flow coordinates, useHandleConnections was removed and the Handle type is now HandleBounds.

Curious about what else is new? Check out the new features.

Migration guide

Before you start to migrate, you need to update the React Flow package.

npm install @xyflow/react@latest

1. Requirements

Zustand 5 (only necessary if you are using Zustand in your project)

Before you continue, you need to update Zustand to version 5. You can do this by running the following command:

npm update zustand@latest

You can use the official Zustand migration guide  to learn more about the changes in Zustand 5.

React 18 or higher

React Flow 13 requires React 18 or higher. If you are using an older version of React, you need to update it to version 18 or higher. You can do this by running the following command:

npm install react@latest react-dom@latest

2. Change handling

onNodesChange and onEdgesChange now receive a NodeChangeset and EdgeChangeset

The onNodesChange and onEdgesChange handlers now receive a NodeChangeset and EdgeChangeset instead of an array of changes. The changesets are iterable and can be used to apply the changes to your nodes and edges.

Old API

import { applyNodeChanges, applyEdgeChanges } from '@xyflow/react'; const onNodesChange = (changes) => { setNodes((nds) => applyNodeChanges(changes, nds)); }; const onEdgesChange = (changes) => { setEdges((eds) => applyEdgeChanges(changes, eds)); };

New API

With the new API there is no need to import applyNodeChanges and applyEdgeChanges (they are no longer exported). The changesets have an applyTo() method that can be used to apply the changes.

const onNodesChange = (changes) => { setNodes((nds) => changes.applyTo(nds)); }; const onEdgesChange = (changes) => { setEdges((eds) => changes.applyTo(eds)); };

Change types were renamed or removed

While revising the change handling system, we also simplified the change types by removing the node and edge prefixes. This means that the change types are now more generic and can be used for both nodes and edges.

The NodeChange and EdgeChange union types still exist.

3. Store access

Replace useStore with specialized hooks

In order to improve the performance we split up the store into multiple smaller stores, each responsible for a specific part of the state. This allows React Flow to only re-render the components that are affected by a particular state change, rather than re-rendering or at least re-calling the useStore selectors whenever any part of the state changes.

We are now exporting these hooks to access the stores, together with a type for the state of each store:

Old API

import { useStore } from '@xyflow/react'; const nodeLookup = useStore((state) => state.nodeLookup);

New API

import { useNodesStore } from '@xyflow/react'; const nodeLookup = useNodesStore((state) => state.nodeLookup);

The use...Store hooks no longer take an equality function as an argument. You should switch to the exported useShallow or the new useEqualSelector selector instead. The previous useStore hook is no longer available.

Old API

import { useStore } from '@xyflow/react'; import { shallow } from 'zustand/shallow'; const { minZoom, maxZoom } = useStore( (s) => ({ minZoom: s.minZoom, maxZoom: s.maxZoom }), shallow, );

New API

import { useOptionsStore, useShallow } from '@xyflow/react'; const { minZoom, maxZoom } = useOptionsStore( useShallow((s) => ({ minZoom: s.minZoom, maxZoom: s.maxZoom })), );

Rename useStoreApi to useReactFlowStoreApi

This is mostly a renaming of the useStoreApi hook to useReactFlowStoreApi to prevent confusion with the original Zustand hook. Because we split up the store, you also need to specify which store you want to access:

const store = useReactFlowStoreApi(); const nodesStoreState = store.nodesStore.getState();

The hook returns a ReactFlowStoreApi object. You can access the state of the individual stores directly via:

  • store.nodesStore.getState()
  • store.edgesStore.getState()
  • store.viewportStore.getState()
  • store.optionsStore.getState()
  • store.connectionStore.getState()
  • store.selectionStore.getState()

4. Styling and colorMode

Drop colorMode prop and handle it automatically

React Flow 13 no longer supports the colorMode prop. We had a lot of issues, because React Flow applied a class name to its wrapper and didn’t respect the color mode from your site. We are now handling the color mode automatically via data-theme or a “dark” or “light” class name higher in the DOM tree.

If you want to force a certain color mode, you can use the forceColorMode prop, which takes a ColorMode. This will force React Flow to use the specified color mode, regardless of the color mode of your site.

<ReactFlow nodes={nodes} edges={edges} forceColorMode="dark" />

Styles now live in a CSS layer

All styles shipped with React Flow (style.css, base.css and the new xy-theme.css) are now wrapped in a CSS layer called xyflow. Before, they were plain unlayered CSS, so your own rules had to match or beat their specificity and come after them in import order to win. A selector like .react-flow__node often wasn’t enough, and many people ended up using !important or more specific selectors.

The one thing to check is whether your own styles also use layers. Tailwind CSS is a common example, with its different layers. Layers are ordered by when they are first declared. The xyflow layer needs to come after Tailwind’s base layer, so that its reset (preflight) doesn’t override React Flow’s styles, and before the utilities layer, so that your utility classes still win. Declare the layer order once at the top of your main stylesheet:

@layer theme, base, xyflow, components, utilities; @import 'tailwindcss'; @import '@xyflow/react/style.css';

Pane cursor styles moved to a pseudo-element

The pane’s grab and grabbing cursors are now set on a ::before overlay instead of the pane itself. This avoids an expensive style recalculation of the whole flow every time a pan starts or stops. If you customized these cursors, target the pseudo-element:

Old API

.react-flow__pane.draggable { cursor: default; } .react-flow__pane.dragging { cursor: move; }

New API

.react-flow__pane.draggable::before { cursor: default; } .react-flow__pane.dragging::before { cursor: move; }

5. Click and drag thresholds

nodeClickDistance removed in favor of nodeDragThreshold

We removed the nodeClickDistance prop. Clicks on nodes now follow a simpler rule: a click fires unless dragging moved the node, or the pointer was released outside of it. Clicks with small pointer movements no longer get lost, which was the main reason to use nodeClickDistance. If you set it, usually to the same value as nodeDragThreshold, you can delete it. If you only set nodeClickDistance, use its value for nodeDragThreshold instead.

paneClickDistance is now paneDragThreshold

paneClickDistance has been replaced by paneDragThreshold which works like nodeDragThreshold now. Previously the pane started panning as soon as you pressed the mouse button, and paneClickDistance only decided whether the gesture still counted as a click. Now the pane doesn’t move at all until the pointer has moved further than paneDragThreshold pixels. Anything shorter is treated as a click and fires onPaneClick.

6. Viewport

Interrupted viewport animations resolve with false

If you don’t pass a duration or don’t await the result, you don’t need to change anything.

Animated viewport functions now resolve with false when something stops the animation before it finishes. Before, their promises never settled in that case, so any code after an await didn’t run.

The resolved value indicates whether the viewport reached its target:

const reached = await fitView({ duration: 800 }); if (!reached) { // the user interrupted the animation or the viewport wasn't ready }

If you run code that depends on the viewport reaching its target, such as a follow-up animation or saving the viewport, check the result first.

padding in fitViewOptions

The padding option in FitViewOptions now gets interpreted as a pixel value if you don’t pass a unit.

7. Connections and handles

onConnectEnd and onReconnectEnd

onConnectEnd and onReconnectEnd now receive to in flow coordinates instead of screen coordinates. You can find it on the FinalConnectionState that gets passed as the last argument.

useHandleConnections and getHandleConnections removed

useHandleConnections and getHandleConnections were removed. You should now use useNodeConnections and getNodeConnections({ nodeId, type, handleId }) from useReactFlow instead. Both return a list of NodeConnection objects.

Handle type is now called HandleBounds

We renamed the Handle type to HandleBounds in order to prevent clashes with the Handle component. This affects anyone who typed fromHandle or toHandle from the ConnectionState.

elevateEdgesOnSelect now defaults to true

By default, edges will now be elevated when selected directly or when their connected nodes are selected.

New features

1. Performance

Performance was the main focus of React Flow 13. The internal store is split into smaller stores, components subscribed to a single node or edge only re-render when that element changes, and the library is compiled with the React Compiler. Most of this works out of the box. To benefit fully, select only the state you need with the new store hooks, useNode and useEdge.

2. NodeChangeset and EdgeChangeset

The new NodeChangeset and EdgeChangeset that are passed to the onNodesChange and onEdgesChange handlers come with some handy utility methods. You can use them to get all changes for a specific node or edge, or to get all changes of a specific type (add, remove, dimensions, position).

// get all changes for a specific node const changesForNode = changes.getForNode('node-1'); // get all changes of a specific type const changesOfType = changes.getByType('remove');

3. Styling, colorMode and a new theme

Color mode is handled automatically

You no longer need to pass the colorMode prop to React Flow. It will automatically detect the color mode of your site and apply the correct styles. If you want to force a certain color mode, you can use the forceColorMode prop.

Layered CSS

Since React Flow 13, we are putting the CSS of React Flow into a separate layer called “xyflow”. This lets you declare the layer order explicitly in your CSS and prevents React Flow styles from being overridden by other styles.

Style import

The import got a bit shorter. You can now import the styles like this:

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

The old import '@xyflow/react/dist/style.css'; import is still supported.

A new theme

React Flow now provides a separate CSS file for the theme called xy-theme.css. It’s the one we use for our website and the examples. If you want to use it, you can import it instead of the default styles:

import '@xyflow/react/xy-theme.css';

4. New hooks

We added some new hooks to complete the React Flow API:

5. New changeParent helper function

useReactFlow now exports a new changeParent helper function that can be used to update the parent of a node. This is useful if you want to move a node from one parent to another.

import { useReactFlow } from '@xyflow/react'; // inside a component: const { changeParent } = useReactFlow(); // inside an event handler for example: changeParent('node-1', 'new-parent-id');

The node will keep its position on screen. You no longer need to manually update its coordinates when changing its parent.

6. Parent nodes no longer need to come first

If you are using subflows, there is good news: With React Flow 13 the order of your nodes no longer matters! Parent nodes can appear after their child nodes in the nodes array.