React Flow v12 is coming soon

We worked hard over the past months and tried to make as few breaking changes as possible (there are some). We are in no rush to release v12, so we’d be happy to hear any early feedback (you can find the migration guide below) so we can adjust the API or redefine new features before launching stable v12. 🚀 The big topics for this version are:

1. Support for SSG/ SSR: you can now render flows on the server (example)
2. Computing flows: new hooks and helper functions to simplify data flows (example)
3. Dark mode: a new base style and easy way to switch between built in color modes (example)

Svelte Flow had a big impact on this release as well. While combing through each line of React Flow, we created framework agnostic helpers, found bugs, and made some under the hood improvements. All of these changes are baked into the v12 release as a welcome side-effect of that launch. 🙌🏻 We also improved the performance for larger flows with the help of Ivan and we are now using TSDoc for a better developer experience in your IDE.

Installation

From now on you can find the package in the xyflow organization:

npm install @xyflow/react

Main features

Now that you successfully migrated to v12, you can use all the fancy features. As mentioned above, the biggest updates for v12 are:

• SSR / SSG: you can define width (or initialWidth), height (or initialHeight) and handles for the nodes. This makes it possible to render a flow on the server and hydrate on the client: example code
  • Details: In v11, width and height were set by the library as soon as the nodes got measured. This still happens, but we are now using measured.width and measured.height to store this information (⚠️ there was an alpha version where this was called computed which is now measured). The positionAbsolute attribute doesn't get exposed to the user nodes anymore. In the previous versions there was always a lot of confusion about width and height. It’s hard to understand, that you can’t use it for passing an actual width or height. It’s also not obvious that those attributes get added by the library. We think that the new implementation solves both of the problems: width and height are optional attributes that can be used to define dimensions and the measured dimensions are stored in measured.
• Computing Flows: The new hooks useHandleConnections and useNodesData and the new updateNode and updateNodeData functions (both are part of useReactFlow) can be used to manage the data flow between your nodes: example code
  • Details: Working with reactive flows is super common. You update node A and want to react on those changes in the connected node B. Until now everyone had to come up with a custom solution. With this version we want to change this and give you performant helpers to handle this.
• Dark mode and css variables: React Flow now comes with a built-in dark mode, that can be toggled by using the new colorMode prop (”light”, “dark” or “system”): example code
  • Details: With this version we want to make it easier to switch between dark and light modes and give you a better starting point for dark flows. If you pass colorMode=”dark”, we add the class name “dark” to the wrapper and use it to adjust the styling. To make the implementation for this new feature easier on our ends, we switched to CSS variables for most of the styles. These variables can also be used in user land to customize a flow.

More features and updates

There is more! Besides the new main features, we added some minor things that were on our list for a long time. We also started to use TSDoc for a better DX. We already started to add some docs for some types and hooks which should improve the developer experience.

• useConnection hook: With this hook you can access the ongoing connection. For example, you can use it for colorizing handles styling a custom connection line based on the current start / end handles.
• Controlled viewport: This is an advanced feature. Possible use cases are to animate the viewport or round the transform for lower res screens for example. This features brings two new props: viewport and onViewportChange.
• ViewportPortal component: This makes it possible to render elements in the viewport without the need to implement a custom node.
• useInternalNode() / getInternalNode helper for advanced usage to receive position absolute or handle bounds for example.
• onDelete handler: We added a combined handler for onDeleteNodes and onDeleteEdges to make it easier to react to deletions.
• onBeforeDelete handler: With this handler you can prevent/ manage deletions.
• isValidConnection prop: This makes it possible to implement one validation function for all connections. It also gets called for programmatically added edges.
• Background component: add patternClassName to be able to style the background pattern by using a class name. This is useful if you want to style the background pattern with Tailwind for example.
• onMove callback gets triggered for library-invoked viewport updates (like fitView or zoom-in)
• deleteElements now returns deleted nodes and deleted edges
• add origin attribute for nodes
• add selectable attribute for edges
• Correct types for BezierEdge, StepEdge, SmoothStepEdge and StraightEdge components
• New edges created by the library only have sourceHandle and targetHandle attributes when those attributes are set. (We used to pass sourceHandle: null and targetHandle: null)
• Edges do not mount/unmount when their z-index change
• nodeDragThreshold is 1 by default instead of 0

Internal changes

These changes are not really user-facing, but it could be important for folks who are working with the React Flow store:

• The biggest internal change is that we created a new package @xyflow/system with framework agnostic helpers that can be used be React Flow and Svelte Flow
  • XYDrag for handling dragging node(s) and selection
  • XYPanZoom for controlling the viewport panning and zooming
  • XYHandle for managing new connections
• Rename nodeInternals to nodeLookup that serves as a lookup, but we are not creating a new map object on any change so it’s really only useful as a lookup.
• Separation of user nodes (type Node) and internal nodes (type InternalNode). The internal node stores some more inforamtion like position absolute, handle bounds and a calculated z-index.
• Remove the internal "reset" event and added a "replace" event to be able to update specific nodes.
• Remove connectionNodeId, connectionHandleId, connectionHandleType from the store and added connectionStartHandle.nodeId, connectionStartHandle.handleId, …
• add data-id to edges
• onNodeDragStart, onNodeDrag and onNodeDragStop also get called when user drags a selection (in addition to onSelectionDragStart, onSelectionDrag, onSelectionDragStop)

Migrate from 11 to 12

Before you can try out the new features, you need to do some minor updates:

• A new npm package name: Our name changed from reactflow to @xyflow/react and the main component is no longer a default, but a named import:
  • v11: import ReactFlow from 'reactflow';
  • v12: import { ReactFlow } from '@xyflow/react'; - don't forget to update the style import too!
• Node attribute “measured”: The measured node dimensions are now stored in node.measured. Besides the new name, this is the biggest change.
  • v11: node.width, node.height ,node.positionAbsolute
  • v12: node.measured.width, node.measured.height (⚠️ this was called node.computed in. a previous alpha version) - node.width/ node.height can now be used for SSG
• Updating nodes and edges: We are not supporting node and edge updates with object mutations anymore. If you want to update a certain attribute, you need to create a new node / edge.
  • v11:

      setNodes(nds => nds.map((node) => {
        node.hidden = true;
        return node;
      }));

  • v12:

      setNodes(nds => nds.map((node) => ({
        ...node,
        hidden: true
      })));

• Sub flows: node.parentNode is now called node.parentId
• NodeProps: posX/posY is now called positionAbsoluteX/positionAbsoluteY
• getNodesBounds: type of the second param changed from nodeOrigin to options.nodeOrigin/options.useRelativePosition
  • v11: getNodesBounds(nodes: Node[], nodeOrigin)
  • v12: getNodesBounds(nodes: Node[], { nodeOrigin })
• Typescript only: We simplified types and fixed issues about functions where users could pass a NodeData generic. The new way is to define your own node type for the whole app and then only use that one. The big advantage of this is, that you can have multiple node types with different data structures and always be able to distinguish by checking the node.type attribute.
  • v11: applyNodeChange<NodeData, NodeType>
  • v12: type MyNodeType = Node<{ value: number }, ‘number’> | Node<{ value: string }, ‘text’>; applyNodeChange<MyNodeType>
  • affected functions: useNodes, useNodesState, useEdgesState, applyNodeChange, onInit, applyEdgeChanges , MiniMapProps
• nodeInternals: If you are using nodeInternals via useStore for example, you need to rename it to nodeLookup:
  • v11: const nodeInternals = useStore(s => s.nodeInternals);
  • v12: const nodeLookup = useStore(s => s.nodeLookup);
• Handle component status class names:
  • v11: "connecting" for end handle (hovered or in connection radius)
  • v12: "connectingfrom" = start handle, "connectingto" = end handle (hovered or in connection radius)
• Removal of deprecated functions:
  • getTransformForBounds (new name: getViewportForBounds),
  • getRectOfNodes (new name: getNodesBounds)
  • project (new name: screenToFlowPosition)
  • getMarkerEndId
• applyNodeChanges/applyEdgeChanges: If you wrote your own function for applying changes, you need to handle the new "replace" event. We removed the "reset" event and added a "replace" event that replaces specific nodes or edges.