✨ @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

[moklick]

That wasn't on purpose :/ We will change it back to HandleProps in 12.0.0-next.18

[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).

[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 :)

[jonrimmer]

Having just started experimenting with using v12 for reactive data flow, I'd echo that I found only being able to access a single handle's connections quite limiting and needed to write a custom hook to get all of the connection data to so I could recalculate the node's outputs.

[shripadk]

Yep! Weird decision to only return connections for one handle instead of all handles.

[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?

[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?

[moklick]

probably June

[1yasa]

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

[moklick]

That should be fixed in 12.0.0-next.16

[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.

[TrySpace]

I just updated to typescript 5.4.5 and the problem disappeared... (4.9.3 also still had the issue so I just bumped it to the latest stable one)

[moklick]

Ok, thanks! We need to check this.

[moklick]

Did you install @types/react and @types/react-dom ?

[TrySpace]

Yes, but haven't changed these for 7 months
"@types/react": "^18.2.21",
"@types/react-dom": "^18.2.7",

[moklick]

Could you check the latest release?

[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?

[moklick]

we are currently not working on a Solid Flow thing (even if it would be a super cool thing to have :))

[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

[moklick]

@DaveAldon thanks for the hint! We will try to find out what's not working here.

[moklick]

I checked the example. You need to adjust the getHelperLines function in order to use node.measured.width / node.measured.height instead of node.width / node.height.

[DaveAldon]

Glad it was just a migration mistake. Thanks for taking a look!

[moklick]

Thanks for the feedback :)

[TrySpace]

I'm had some trouble with drag/dropping nodes in and out of group nodes (when using parentNode/parentId the coords are relative to the parent so there's a discrepancy between the absolute positions). What should I use instead of positionAbsolute or should I rather be using the new XYDrag helpers?

I used to be able to do this to create a new node on connect drop (Add Node On Edge Drop Example):

 const onConnectStart: OnConnectStart = useCallback((evt, node) => {
    const { nodeId } = node
    const pNode = nodeId ? getNode(nodeId) : {}
    // @ts-ignore
    parentNode.current = pNode
    connectingNodeId.current = nodeId
  }, [])

  const onConnectEnd: OnConnectEnd = useCallback(
    (event) => {
      if (!connectingNodeId.current) return

      const targetIsPane = (event.target as Element).classList.contains(
        'react-flow__pane'
      )

      if (targetIsPane) {
        // Get mouse position
        const clientX = (event?.clientX as number) || 0
        const clientY = (event?.clientY as number) || 0

        // Convert mouse coordinates to relative position
        const screenPos = screenToFlowPosition({
          x: clientX,
          y: clientY,
        })

        // Get the absolute position of the parent node (if any)
        const parentX = parentNode.current?.positionAbsolute?.x || 0
        const parentY = parentNode.current?.positionAbsolute?.y || 0

        // Subtract parent coords from relative screenPos
        const posX = screenPos.x - parentX
        const posY = screenPos.y - parentY

        const newId = getId()

        const newNode = NewNode({
          id: newId,
          position: { x: posX, y: posY },
          parentId: connectingNodeId.current,
        })

        setNodes((nds) => nds.concat(newNode))

        setEdges((eds) =>
          eds.concat({
            id: newId,
            source: connectingNodeId.current,
            target: newId,
          })
        )
      }
    },
    [screenToFlowPosition]
  )

Without the XYDrag helpers, how would I get the internalNode?

[moklick]

You can use the new helper getInternalNode from useReactFlow. Does that work for you?

[TrySpace]

Yes, that works, thanks!

[TrySpace]

I've noticed that the base css (import '@xyflow/react/dist/base.css') is missing the styles for NodeResizer

When I import '@xyflow/react/dist/style.css' the styles are correct

[moklick]

thanks! will be fixed in the next release.

[Timot05]

Nice work on Reactflow! I'm running reactflow 11.11.2. and I have the same issue described in this ticket where the links are not updating their position when the handles move around. Does V12 provide a workaround for this issue?

[moklick]

I answered in the related issue

[rob-gordon]

It kind of throws me off that reactFlow has an updateNode property on it but not an updateEdge property. I'm trying to update edge labels dynamically with some code that looks like this:

function updateEdgeLabel(id: string, label: string) {
  const rf = useStore.getState().reactFlowInstance;
  if (!rf) return;
  rf.setEdges((edges) =>
    edges.map((edge) => (edge.id === id ? { ...edge, label } : edge))
  );
}

And it works but I think it doesn't update the internals because the rendered label doesn't change size although the text does. (Using default edges, not custom)

[bcakmakoglu]

Can you possibly provide a repro for this? Are you already using v12?
I tried to create a minimal repro for this but didn't have any issues 🤔
Although the repro is in v11

[rob-gordon]

Yeah, I'm using v12. Sure here's a reproduction: https://stackblitz.com/edit/react-ts-nd6nrw?file=index.tsx

[bcakmakoglu]

Interesting, it does look like a bug in v12 :(

[pfebrer]

Hi, I have an issue with types in v12.

I used to define custom nodes as (using reactflow instead of @xyflow/react):

import { 
    NodeProps,
} from '@xyflow/react';

interface CustomNodeData {
    name: string,
}

const MyCustomNode = (props: NodeProps<CustomNodeData>) => {
      return <div></div>
}

But now I get an error like:

Type 'CustomNodeData' is missing the following properties from type 'NodeBase<Record<string, unknown>, string>': id, position, data

I have seen the point about typescript in the discussion's description, but I don't understand how I should change my code 😅

Can someone help? Thanks!

[pfebrer]

Ok, I did:

import { 
    NodeProps,
    Node
} from '@xyflow/react';

type MyNodeType = Node<{
    name: string,
}, "MyNodeType">

const MyCustomNode = (props: NodeProps<MyNodeType>) => {
      return <div></div>
}

Is this how it should be done?

[sabinayakc]

Thats what I did as well to fix the issue. Don't know if thats the way tho?

[dAN0n]

Hi again, I suppose mini map preview was broken after upgrade from next.17 to next.18. Zooming and dragging works but without any elements inside, just gray square with white viewport.

[moklick]

Thanks. Can you open an issue for that?

[dAN0n]

Hi, I opened the issue #4279 as you requested.

[rob-gordon]

Seeing a NodeResizer bug (not sure if it's related to @tonyf's or not) where keepAspectRatio needs to be true, otherwise edges do not stay bound to the handles.

Reproduction: https://stackblitz.com/edit/vitejs-vite-xtvjgu?file=src%2FApp.tsx

[sanchezfdezjavier]

Thanks the update @moklick, awesome work! Any news about the release of the stable?