Skip to Content

Migrate to Svelte Flow 2.0

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

Migration guide

Before you start to migrate, you need to update the Svelte Flow package.

npm update @xyflow/svelte@latest

1. No more $derived for hooks

With Svelte Flow 2 we removed the necessity of using $derived for hooks. You can now use the hooks directly without the need to wrap them in a $derived.

Old API

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

New API

let nodeData = useNodesData(() => ({ nodeIds: [connections.current[0]?.source] }));

This change affects the following hooks:

  • useInternalNode
  • useNodesData
  • useNodeConnections
  • useOnSelectionChange

2. Rename useStore to useSvelteFlowStore

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

3. Drop colorMode prop and handle it automatically

Svelte Flow 2 no longer supports the colorMode prop. 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. This will force Svelte Flow to use the specified color mode, regardless of the color mode of your site.

<SvelteFlow forceColorMode="dark" />

4. Subflow nodes ordering is now obsolete

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.

5. 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, so if the xyflow stylesheet is imported after Tailwind, the xyflow layer can override your utility classes. To avoid that, declare the layer order once at the top of your main stylesheet:

@layer xyflow, theme, base, components, utilities;
 
@import 'tailwindcss';
@import '@xyflow/svelte/style.css';

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

New features

1. onnodeschange and onedgeschange handlers

TODO

2. New hooks

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

3. 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');

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

5. Export xy-theme.css

React 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 like:

import '@xyflow/svelte/xy-theme.css';

6. Layered CSS

Since Svelte Flow 2, we put the library CSS into a separate layer called “xyflow”. This enables explicitly declare layer order in your CSS and prevents Svelte Flow styles from being overridden by other styles. You can read more about CSS layers here .

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