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:
- Hooks: hooks no longer need
$derived,useStoreis nowuseSvelteFlowStoreanduseNodesanduseEdgesare read-only. - 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,getHandleConnectionswas 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 Svelte Flow package.
npm install @xyflow/svelte@latest1. 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.