✨ @xyflow/react - React Flow v12 next

[moklick]

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.

[bcakmakoglu]

Incredible work as always and I am very excited to try these features out 🌻

[thmsgbrt]

Amazing update guys! Can't wait to try it out 🚀

[juspky]

Very nice! v12 seems to work perfectly for me.

small nitpick, why is project now called screenToFlowPosition when you actually need to pass clientX, clientY?
the name could miss lead someone to pass screenX, screenY. which only works if xyflow is at the top left of the screen.

[moklick]

That's a good point. We wanted to rename the function, because project is a bad name to search for and also and not understandable. We thought, that it makes sense here to have the word screen in the function name, so that it's clear that you can convert a screen position to a flow position. We could still rename it, but I like screenToFlowPosition better than clientToFlowPosition. Do you have another idea?

[juspky]

I think the new name is much better then project aswell.

I can just speak from my perspective but when migrating to v12 the naming made me question if I had to pass screenXY now.
So I had to try out how both behave and realized its clientXY.

I can see people getting confused why their position is off when assuming they need to pass screenXY, especially if they are not that experienced in web development and don't know there is a difference between screen and client coordinates.

Maybe renaming the parameter to clientPosition would help a bit.

But having the function name say screen and the parameter say client looks off too.

If this was my codebase I would probably just rename it to clientToFlowPosition

[moklick]

Good idea! We will also add more annotations. With the next update it will look like this in your IDE:

[juspky]

Yeah thats great!

I'm happy to see the snapToGrid option too, this will be useful to me.

[HiChen404]

Amazing!!!

[ProfDeCube]

Do we know when v12 is likely to be available on a stable release?
We're currently using react flow in a live system and want to upgrade to allow easier addition of new features.

[moklick]

Probably by end of March.

[danieldunderfelt]

I had just started using react-flow and the update was pretty painless! My only issue is that the connection argument of the isValidConnection prop on <ReactFlow /> is of type Connection | EdgeBase, but EdgeBase is not exported. This makes it inconvenient to make an external function that is called with the connection argument, as I can't include EdgeBase in its arguments. Can EdgeBase be exported or removed from the type of the connection argument?

[moklick]

thanks for the feedback @danieldunderfelt . This should be fixed in 12.0.0-next.10

[rob-gordon]

Looking forward to this next release! I'm really interested in the computing flows features, but the example doesn't appear to be working, at least for me. Thanks for the great library!

[moklick]

Thanks for the hint! We introduced a change and didn't update the example. It should work again.

[danieldunderfelt]

I also noticed that when I drag from a handle, lots of stuff gets selected, including a chunk of the background and inputs in the node components. This didn't happen when using v11.

[moklick]

are you using Safari?

[danieldunderfelt]

Maybe, this is in a Neutralino.js app. It uses the native browser of the OS it runs in.

[moklick]

ok, I will check it. I know that we had this bug before.

[danieldunderfelt]

Great, thanks!

[moklick]

will be fixed in 12.0.0-next.11

[bpiggin]

Really looking forward to this release, great work! 🚀

[hiepnguyen3001]

It seems v12 doesn't support setNodes with immer produce.

I got TypeError: Cannot assign to read only property 'positionAbsolute' of object '#<Object>' when I tried to drag a node after updating nodes like this :

   setNodes(produce((draft) => {
      for (const node of draft) {
        node.selected = true;
      }
    }))

Is there a neater way to update nodes with nested object as data than spread operator at every level?

[moklick]

we now have updateNode and updateNodeData:

for (const node of nodes) {
  updateNode(node.id, { selected: true });
}

[li-jia-nan]

in V11：

import type { HandleProps } from "reactflow";

in V12：

import type { HandleProps } from "@xyflow/react";  // "@xyflow/react" has no exported member 'HandleProps'

[saswatax]

change it to:

import type { HandleComponentProps }  from "@xyflow/react";

[li-jia-nan]

thx

[danieldunderfelt]

I can't get the useHandleConnections hook to work like in the v12 data flow example. It always returns 0 connections. I need to use getEdges() from useReactFlow() to find all connections for a node. How is this supposed to work? Using Beta 11 (but the situation was the same for 9 and 10 too).

[danieldunderfelt]

That only works for one handle ID, but I have an array of them and hooks don't work in loops. I think this hook is severely limited and it fails silently. I had a lot of issues trying to figure out what was wrong.

Ideally it would return all connections to the node if no handle ID is provided.

[bcakmakoglu]

Though that's not what it was designed for, if you need all edges that belong to a node, you can always just call getConnectedEdges and use that result to get the data you need.

const connectedEdges = getConnectedEdges(nodesToCheck, edges)

[bcakmakoglu]

Keep in mind that you are using a hook that is called useHandleConnections, the name, imo, clearly implies that you are getting the connections of a specific handle and not of all handles or the node itself.
Otherwise the naming would probably be useHandlesConnections or useNodeConnections or something like that :)

Though you are, of course, always free to open a feature-request for this or open a PR with your proposed changes that make it clear why your implementation would be better.
Contributions are always welcome ^^

[danieldunderfelt]

I made a custom hook for this and called it exactly useNodeConnections 👍

To me it seems more useful to get all the connections to the node, and the name useHandleConnections doesn't exclude that in my mind.

Does getConnectedEdges cause the component to rerender on connection changes?

[bcakmakoglu]

Not necessarily, no.
For that purpose it's probably better to use useStore with a proper selector :)

[sachinragul]

I am rendering data from backend , so the initial position of x and y is 0. In the UI node will be one after the other meaning one node i can see , rest are behind the first node. So i used onNodeDrag , so that when a node is dragged its x and y position will change, but it is creating a copy object on each drag.Is there any props that i can use for dragging the node , on drag i want to update the node x and y position

[moklick]

Is this something specific about v12? Dragging nodes should work the same way as in v11. React Flow handles it for you, you just need to apply the changes as explained here: https://reactflow.dev/learn/concepts/core-concepts#basic-functionality

[vanBassum]

Hello guys, I was trying to test the computing flow feature. While doing so, I noticed that the edges do weird things. I don't know if this is something in V12 or also in earlier versions. Also, It could very well be something I am doing wrong. My React knowledge is lacking to say the least.

Here is a branch, checkout and move the nodes around a bit.
https://github.com/vanBassum/DataFlow/tree/WierdEdges

[moklick]

You need to update the style import as well:

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

[vanBassum]

Ah, I thought importing the style in the flow.js was enough. This fixes my issue, thanks for the support.

Awesome feature btw!

[collinsleewyatt]

I also forgot to change this import and didn't get a warning in my IDE; it doesn't look like my editor is set up to give warnings for css imports. It might be worth putting it in the migration guide because I'd guess that some developers have similar setups.

[moklick]

We will publish a proper migration guide on our website when React Flow 12 is launched.

[prajwalkulkarni]

Great new additions!
I would particularly like to try the SSR/SSG feature, however, on opening the example code link, it says "Out of Credits", may I know how can I run the example code either locally or in a sandboxed environment?

[moklick]

We are still not 100% sure how to handle measured node dimensions. This is an alternative approach #4054 - Feedback is highly appreciated!

[bogris]

Hi all,

In order to celebrate the new typings on nodes, I managed to put toghether a few lines of generic that help with custom compoents. I hope someone else may find this usefull:

export interface NodeOneData extends Record<string, unknown> {
  label?: string;
  width: number;
  height: number;
}

interface NodeTwoData extends Record<string, unknown> {
  label?: string;
  value: number;
}

this defiens the actual node type and the data you expect from it

interface NodeDataMap {
  'custom-one': NodeOneData;
  'custom-two': NodeTwoData;
}

This one is used to define the custom node React components

type NodeComponentsMap = {
  [K in keyof NodeDataMap]: FC<NodeProps<Node<NodeDataMap[K], K>>>;
};

example:

export const CustomNodeOne:NodeComponentsMap['custom-one'] = (props) => {
  const { id, selected, width, height, data } = props;

used to define the types of all nodes.

export type AllNodeTypes = {
  [K in keyof NodeDataMap]: Node<NodeDataMap[K], K>
}[keyof NodeDataMap];

examples:

const mockInitialNodes: AllNodeTypes[] = [ ... ]

    const newNode: AllNodeTypes = {
           type: 'custom-one', 
           data: { ... } //typed based on the type above

[kevingyang]

Hi, it seems like the reactive-flow repo is no longer typesafe (there are type issues related to the NodeData type). Could you guys update the example? Thanks a bunch!

[li-jia-nan]

I don't know which api should I use to delete a node ? Are there any differences between them ?

const reactFlow = useReactFlow<Node, Edge>();

reactFlow.setNodes(nodes => nodes.filter(node => node.id !== id));

const reactFlow = useReactFlow<Node, Edge>();

reactFlow.deleteElements({ nodes: [{ id }] });

[bcakmakoglu]

While the result of both of these actions will look the same (a node is removed), internally different things do happen and are communicated to you in a different way.

setNodes will basically perform a direct change on the internal state. You won't receive any changes via the designated props (onNodesChange/ onEdgesChange).

deleteElements on the other hand will create changes and send them through onNodesChange/ onEdgesChange so you can apply them to your nodes/edges.
This might be useful if you want to keep track of these changes for an undo/redo feature for example.

[li-jia-nan]

thank you for your reply.

[mastercoms]

It seems like snapToGrid is default true, which breaks some behavior vs. v11. Should be noted in the upgrade notes, or default to false.

[li-jia-nan]

can you export the onNodeDragEnd function, be like:

import React from "react";
import type { NodeProps, Node } from "@xyflow/react";

const MyNode: React.FC<NodeProps<Node>> = props => {
  const { onNodeDragEnd } = props;
  ……
}

export default MyNode;

[wlc534]

When will React Flow v12 be released in the official version, and whether the example on the official website will be updated synchronously after the release, and there will be projects using reactflow in early April, looking forward to v12

[dAN0n]

Interactive minimap doesn't work with touchscreen (zoomable pannable has no effect on iPhone 13 Safari for example), is it intended behavior?

[prajwalkulkarni]

I just went through the SSG/SSR example, and the rendered output is fully static and I'm not able to perform any action on the output (move across the viewport, drag the nodes, etc). Is the component not getting hydrated on the client? Am I missing something? Any help is appreciated. I'm attaching a video for reference.

I added a new node (through the code) and set its position such that it is rendered out of the react flow viewport, however, I'm not able to view that node by dragging the canvas/background. Moreover, the nodes within the viewport are also not draggable. When I tried zooming in, I could not zoom in on the canvas, instead, the browser tab zoomed in.
cc @moklick

react-flow.mp4

[moklick]

That is the expected behaviour. In astro you need to add a client directive (like client:load) to enable hydration https://docs.astro.build/de/reference/directives-reference/#client-directives

[EtaJx]

any plans of stable version this month?

[1yasa]

setNodes(nodes=>{}), the callback nodes has not computed attr(useNodes has), i guess you guys forgot this.

[IanLondon]

It seems like the types for Handle are wrong: eg Property 'type' does not exist on type 'IntrinsicAttributes'. (same with id and other props). Btw, I get this directly from using <Handle id="foo" type="target>, it's not related to HandleProps being renamed to HandleComponentProps.

For the <ReactFlow> component itself, I also get 'ReactFlow' cannot be used as a JSX component., Its return type 'ReactNode' is not a valid JSX element.

[moklick]

Where do you get this? What is your dev setup?

[IanLondon]

I got the type error from tsc --noEmit, using @xyflow/react 12.0.0-next.14 in a Next.js project. I'm running Linux Mint, node 20.8.1, typescript 4.9.4, next.js 13.5.1. Please LMK if there's any more info I can provide.

It's purely a TypeScript error, I can build it and run it in the browser fine following the migration guide.

[tonyf]

I'm trying to use NodeResizer but running into a few issues.

1. A dimensions change with resizing: false isn't being triggered on onResizeEnd. Looking at the source, this should be getting triggered? Instead, I'm having to manually call it.
2. measured dimensions aren't being updated with the dimensions changes, only the node's height and width attributes. While the node looks the correct size, you can tell that the measured size differs based upon where edges seem to connect on the node. The lack of appropriate updates is also reflected in the node storage.
3. When loading from persistent state, measured is set to NodeSelector's minHeight and minWidth values instead of the proper dimensions. This seems related to 2. as the measured dimensions up to date.

Using nextjs 13 + zustand + liveblocks

[tonyf]

On loading from storage, visually everything seems fine despite node.measured.height and node.measured.width not matching node.height and node.width.

But, after resizing, this is no longer the case:

[tonyf]

This visual issue (edge starting from original size of the node) can by fixed by using useUpdateNodeInternals but measured height and width are still incorrect

[moklick]

This sounds weird and I can't reproduce this.

1. The resize end event is fired here: https://github.com/xyflow/xyflow/blob/main/packages/react/src/additional-components/NodeResizer/NodeResizeControl.tsx#L108-L112

2. measured dimensions get updated whenever a dimension change comes in https://github.com/xyflow/xyflow/blob/main/packages/react/src/utils/changes.ts#L100-L106 how are you applying the changes?

3. I don't understand this point. The measured dimensions are based on the content of a node. If you resize a node, width and height attributes get set and used to define the dimensions. You can persist those dimensions and use width and height to set the dimensions on load.

Is it possible that you implemented a custom onNodesChange function? Do you have a codesandbox or repo I could look at?

[tonyf]

Hm

1. It seems like while that function is defined there, it's not actually being called in XYResizer
2. That's what I thought. I just replicated that block of code right after applyChanges in onNodesChange and things worked fine.
3. So that's what I believed should be happening. However, on mount, it seems like those values are not actually used instead of minHeight and minWidth from the NodeResizer

I do but I downgraded to v11 which resolved these issues. Let me see what I can send from an old commit. Have an email I can send it to?

[tonyf]

Fix for (1) #4176

[matthewgapp]

Sweeet. Any chance we'll see a solid js port soon?

[DaveAldon]

I've run through the Helper Lines example code and migrated it to v12, but in this version it's missing the lines for the right and bottom sides of all nodes. I've added other calculations for centers too but they never seem to trigger. Works great in v11. Happy to supply a basic repo with this happening.

1. Downloaded the Helper Lines source code
2. Changed all reactflow imports to @xyflow/react
3. Changed style imports from reactflow/dist/style.css to @xyflow/react/dist/style.css
4. Importing <ReactFlow> as { ReactFlow } from '@xyflow/react'
5. npm run dev

Below happens:

Untitled.mov