Migrate to React Flow 13
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:
- Requirements: update to React 18 and Zustand 5.
- Change handling:
onNodesChangeandonEdgesChangereceive changesets, and the change types were renamed. - Store access:
useStoreanduseStoreApiwere replaced by specialized store hooks. - Styling and
colorMode: color mode is detected automatically, styles live in a CSS layer and the pane cursor moved to a pseudo-element. - Click and drag thresholds:
nodeClickDistancewas removed andpaneClickDistanceis nowpaneDragThreshold. - Viewport: interrupted animations resolve with
falseand unitlessfitViewOptions.paddingvalues are pixels. - Connections and handles:
onConnectEnduses flow coordinates,useHandleConnectionswas removed and theHandletype is nowHandleBounds.
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@latest1. 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@latestYou 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@latest2. 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.
NodeDimensionChange→DimensionChangeNodePositionChange→PositionChangeNodeSelectionChange, EdgeSelectionChange→SelectionChangeNodeRemoveChange, EdgeRemoveChange→RemoveChangeNodeAddChange, EdgeAddChange→AddChangeNodeReplaceChange, EdgeReplaceChange→ReplaceChange
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:
useNodesStorereturnsNodesStoreuseEdgesStorereturnsEdgesStoreuseViewportStorereturnsViewportStoreuseOptionsStorereturnsReactFlowStateuseConnectionStorereturnsConnectionStoreuseSelectionStorereturnsSelectionStore
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.