Skip to Content
Svelte Flow 2 is out! Read the announcement →

Migrate to Svelte Flow 2

If you are looking for the Svelte Flow 1.x docs, please refer to v1.svelteflow.dev .

Svelte Flow 2 makes hooks easier to use, gives you full control over node and edge changes and improves performance. Most apps only need a few small changes to upgrade. For a full list of changes, see the release notes .

Overview of the changes:

  1. Hooks: hooks no longer need $derived, useStore is now useSvelteFlowStore and useNodes and useEdges are read-only.
  2. Styling and colorMode: color mode is detected automatically, styles live in a CSS layer and the pane cursor moved to a pseudo-element.
  3. Click and drag thresholds: nodeClickDistance was removed and paneClickDistance is now paneDragThreshold.
  4. Viewport: interrupted animations resolve with false and unitless fitViewOptions.padding values are pixels.
  5. Connections and handles: onconnectend uses flow coordinates, getHandleConnections 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 Svelte Flow package.

npm install @xyflow/svelte@latest

1. Hooks

No more $derived for hooks

With Svelte Flow 2 we removed the necessity of using $derived for hooks. Hooks that depend on reactive values now accept a function that returns their parameters instead.

Old API

import { useNodesData } from '@xyflow/svelte'; let nodeData = $derived(useNodesData([connections.current[0]?.source]));

New API

import { useNodesData } from '@xyflow/svelte'; let nodeData = useNodesData(() => ({ nodeIds: [connections.current[0]?.source] }));

This change affects the following hooks:

Rename useStore to useSvelteFlowStore

This is a simple rename of the hook to prevent confusion with other libraries. If you are using useStore, you need to rename it to useSvelteFlowStore.

useNodes and useEdges are read-only

useNodes and useEdges no longer return setters. Use updateNode and updateEdge from useSvelteFlow to change a single element, or update the nodes and edges you bind to <SvelteFlow />. Read more in our Handling Updates guide.

Old API

import { useNodes } from '@xyflow/svelte'; const nodes = useNodes(); nodes.update((nds) => nds.map((n) => (n.id === 'node-1' ? { ...n, data: { label: 'Updated' } } : n)));

New API

import { useSvelteFlow } from '@xyflow/svelte'; const { updateNode } = useSvelteFlow(); updateNode('node-1', { data: { label: 'Updated' } });

2. Styling and colorMode

Drop colorMode prop and handle it automatically

Svelte Flow 2 no longer supports the colorMode prop and the useColorMode hook was removed. We had a lot of issues, because Svelte 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 Svelte Flow to use the specified color mode, regardless of the color mode of your site.

<SvelteFlow bind:nodes bind:edges forceColorMode="dark" />

Styles now live in a CSS layer

All styles shipped with Svelte 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 .svelte-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 Svelte 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/svelte/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

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

New API

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

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

4. 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 from useSvelteFlow 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. The default padding for fitView and fitBounds is now 5%.

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

getHandleConnections removed

getHandleConnections was removed. You should now use useNodeConnections or getNodeConnections({ nodeId, type, handleId }) from useSvelteFlow instead. Both return a list of NodeConnection objects. The HandleConnection type was removed as well.

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.

New features

1. onnodeschange and onedgeschange handlers

With the new onnodeschange and onedgeschange handlers you can monitor and control every change to your nodes and edges. Svelte Flow calls them with a NodeChangeset or EdgeChangeset before it applies the changes. Whatever is left in the changeset after your handler returns gets applied to your nodes and edges automatically.

<script lang="ts"> import { SvelteFlow, type Node, type Edge, type NodeChangeset } from '@xyflow/svelte'; let nodes = $state.raw<Node[]>([ { id: 'locked', position: { x: 0, y: 0 }, data: { label: 'Locked' } }, { id: 'node-2', position: { x: 0, y: 100 }, data: { label: 'Node 2' } }, ]); let edges = $state.raw<Edge[]>([]); function onnodeschange(changes: NodeChangeset<Node>) { // inspect changes, e.g. all removals const removed = changes.getByType('remove'); if (removed.length > 0) { console.log('removing nodes', removed); } // drop changes you don't want: the locked node can't be moved or deleted changes.removeForNode('locked'); // no need to call changes.clear(): the remaining changes will be applied } </script> <SvelteFlow bind:nodes bind:edges {onnodeschange} />

The changesets come with some handy utility methods. You can get all changes for a specific node or edge, all changes of a specific type (add, remove, replace, update, data, select, position, dimensions) or iterate over every change:

function onnodeschange(changes: NodeChangeset<Node>) { // all changes for a specific node const changesForNode = changes.getForNode('node-1'); // all changes of a specific type const removeChanges = changes.getByType('remove'); // every change in order for (const change of changes) { console.log(change.type, change.id); } }

If you want to apply the changes yourself, for example to sync them with a backend, apply them with changes.applyTo() and call changes.clear() so Svelte Flow skips them:

function onnodeschange(changes: NodeChangeset<Node>) { nodes = changes.applyTo(nodes); saveToBackend(changes.toArray()); changes.clear(); }

To learn more about updating nodes and edges and handling changes, check out the Handling Updates guide.

2. Performance

Svelte Flow 2 processes nodes and edges more efficiently and avoids a full style recalculation when the pane cursor changes while panning. Most of this works out of the box. To benefit fully, subscribe only to the elements you need with the new useNode and useEdge hooks.

3. Styling, colorMode and a new theme

Color mode is handled automatically

You no longer need to pass the colorMode prop to Svelte 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. Read more in the theming guide.

Layered CSS

Since Svelte Flow 2, we are putting the CSS of Svelte Flow into a separate layer called “xyflow”. This lets you declare the layer order explicitly in your CSS and prevents Svelte 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/svelte/style.css';

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

A new theme

Svelte 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/svelte/xy-theme.css';

4. New hooks

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

5. New changeParent helper function

useSvelteFlow 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 { useSvelteFlow } from '@xyflow/svelte'; // inside a component: const { changeParent } = useSvelteFlow(); // 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 Svelte Flow 2 the order of your nodes no longer matters! Parent nodes can appear after their child nodes in the nodes array.