# Vue Flow Documentation
What is Vue Flow?
Vue Flow is a library that allows you to create interactive, node-based user
interfaces: flowcharts, diagrams, visual programming tools, and workflows inside
your vue applications. It supports theming, custom nodes and edges, a library
of shadcn UI components, and offers a large collection of examples for rapid development.
Developers can leverage the Vue Flow Pro platform for advanced features like
real-time collaboration, complex layouts, and enhanced performance, making it
suitable for both simple and large-scale, production-ready visual applications.
## Learn
### Quick Start
This page will take you from zero to a working Vue Flow app in a few minutes. You'll
learn how to install Vue Flow, configure it, and create your first flow. From
there you can check out the examples,or dive into the API docs. If you want to get
up and running as soon as possible, you're in the right place!
#### Installation
To install Vue Flow in an existing Vue project, run the following command:
```bash copy npm2yarn
npm install @xyflow/vue
```
Using Nuxt? Head to [Usage with Nuxt](/learn/nuxt), which covers the same setup plus what the
server renders.
#### Usage
The `@xyflow/vue` package exports the `` component, which is the
entrypoint for your flow. Importing the default styles and defining a handful of
nodes and edges are all we need to get started!
There are a few things to pay attention to here:
* You must import the Vue Flow stylesheet.
* Each node must have a unique id.
* Using `shallowRef` is preferable for nodes and edges to avoid costly deep reactivity.
* The `` component inherits the size of its parent. Make sure to wrap it in an element with
explicit dimensions.
```vue
```
#### Result
Et voila. You've already created your first interactive flow!
Example: learn/quickstart
##### index.ts
```ts
import { createApp } from 'vue';
import App from './App.vue';
import './index.css';
createApp(App).mount('#app');
```
##### index.html
```html
Vue Flow Example
```
##### xy-extras.css
```css
/*
Extras for the xyflow examples. These styles sit on top of `@xyflow/vue/xy-theme.css`, which has to be
imported before this file. They only add what the library theme doesn't ship with.
*/
.vue-flow__panel {
color: var(--xy-theme-panel-text);
}
.vue-flow__node {
box-shadow: var(--xy-node-boxshadow-default);
}
.vue-flow__node-resizer {
border-radius: 0;
border: none;
}
/*
Custom Example CSS - This CSS is to improve the example experience.
You can remove it if you want to use the default styles.
New Theme Classes:
.xy-theme__button - Styles for buttons.
.xy-theme__input - Styles for text inputs.
.xy-theme__checkbox - Styles for checkboxes.
.xy-theme__select - Styles for dropdown selects.
.xy-theme__label - Styles for labels.
.xy-theme__range - Styles for range sliders (set --range-progress for the filled part).
Use these classes to apply consistent theming across your components.
*/
:root {
--color-primary: var(--xy-theme-primary);
--color-background: light-dark(#fefefe, #1a1b1e);
--color-hover-bg: light-dark(#f6f6f6, #24262c);
--color-disabled: light-dark(#76797e, #8b9099);
--color-primary-muted: color-mix(
in srgb,
var(--color-primary) 40%,
transparent
);
--color-primary-focus: color-mix(
in srgb,
var(--color-primary) 30%,
transparent
);
}
.xy-theme__button-group {
display: flex;
align-items: center;
.xy-theme__button:first-child {
border-radius: 100px 0 0 100px;
}
.xy-theme__button:last-child {
border-radius: 0 100px 100px 0;
margin: 0;
}
}
/* Custom Button Styling */
.xy-theme__button {
display: inline-flex;
align-items: center;
justify-content: center;
height: 2.5rem;
padding: 0 1rem;
border-radius: 100px;
border: 1px solid var(--color-primary);
background-color: var(--color-background);
color: var(--color-primary);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
box-shadow: var(--xy-node-boxshadow-default);
cursor: pointer;
}
.xy-theme__button.active {
background-color: var(--color-primary);
color: white;
border-color: var(--color-primary);
}
.xy-theme__button.active:hover,
.xy-theme__button.active:active {
background-color: var(--color-primary);
opacity: 0.9;
}
.xy-theme__button:hover {
background-color: var(--xy-controls-button-background-color-hover-default);
}
.xy-theme__button:active {
background-color: var(--color-hover-bg);
}
.xy-theme__button:disabled {
color: var(--color-disabled);
opacity: 0.8;
cursor: not-allowed;
border: 1px solid var(--color-disabled);
}
.xy-theme__button > span {
margin-right: 0.2rem;
}
/* Add gap between adjacent buttons */
.xy-theme__button + .xy-theme__button {
margin-left: 0.3rem;
}
/* Example Input Styling */
.xy-theme__input {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 7px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
}
.xy-theme__input:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Specific Checkbox Styling */
.xy-theme__checkbox {
appearance: none;
-webkit-appearance: none;
width: 1.25rem;
height: 1.25rem;
border-radius: 7px;
border: 2px solid var(--color-primary);
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
cursor: pointer;
display: inline-block;
vertical-align: middle;
margin-right: 0.5rem;
}
.xy-theme__checkbox:checked {
background-color: var(--color-primary);
border-color: var(--color-primary);
}
.xy-theme__checkbox:focus {
outline: none;
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Dropdown Styling */
.xy-theme__select {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 50px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
margin-right: 0.5rem;
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__select:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
.xy-theme__label {
margin-top: 10px;
margin-bottom: 3px;
display: inline-block;
color: var(--xy-theme-panel-text);
}
/* Range Slider Styling */
.xy-theme__input[type='range'],
.xy-theme__range {
-webkit-appearance: none;
appearance: none;
display: block;
width: 100%;
height: 0.5rem;
padding: 0;
border: none;
border-radius: 100px;
background: transparent;
cursor: pointer;
}
.xy-theme__input[type='range']:focus,
.xy-theme__range:focus {
outline: none;
box-shadow: none;
}
.xy-theme__input[type='range']::-webkit-slider-runnable-track,
.xy-theme__range::-webkit-slider-runnable-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: linear-gradient(
to right,
var(--color-primary-muted) 0%,
var(--color-primary-muted) var(--range-progress, 0%),
var(--color-hover-bg) var(--range-progress, 0%),
var(--color-hover-bg) 100%
);
}
.xy-theme__input[type='range']::-webkit-slider-thumb,
.xy-theme__range::-webkit-slider-thumb {
-webkit-appearance: none;
appearance: none;
width: 1.25rem;
height: 1.25rem;
margin-top: -0.375rem;
border-radius: 50%;
border: 2px solid var(--color-background);
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-track,
.xy-theme__range::-moz-range-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: var(--color-hover-bg);
}
.xy-theme__input[type='range']::-moz-range-thumb,
.xy-theme__range::-moz-range-thumb {
width: 1.25rem;
height: 1.25rem;
border: none;
border-radius: 50%;
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-progress,
.xy-theme__range::-moz-range-progress {
height: 0.5rem;
border-radius: 100px 0 0 100px;
background: var(--color-primary-muted);
}
```
##### index.css
```css
@import url('./xy-extras.css');
html,
body {
margin: 0;
font-family: sans-serif;
box-sizing: border-box;
}
#app {
width: 100vw;
height: 100vh;
}
```
##### App.vue
```vue
```
#### Next steps
Where to head next depends on what you need to know and how you like to learn.
Check out the core concepts to better understand how Vue Flow works and the
common terminology we use throughout our docs. If you're interested in how to
render your own custom nodes in a flow, then the customization docs are for you.
If you just want to see some code, head over to our examples to see how to implement
different features and functionality.
### Usage with Nuxt
[Nuxt](https://nuxt.com) renders your pages on the server by default and Vue Flow works there out of
the box. How much of your flow ends up in the HTML is up to your node data though, because there is
no DOM to measure on the server.
#### Installation
If you don't have a Nuxt app yet, create one:
```bash copy npm2yarn
npm create nuxt@latest my-flow-app
```
Then install Vue Flow:
```bash copy npm2yarn
npm install @xyflow/vue
```
Finally, add the stylesheet to your Nuxt config. That's the only setup Vue Flow needs, you can leave
`build.transpile` and `vite.ssr.noExternal` alone.
```ts filename="nuxt.config.ts"
export default defineNuxtConfig({
css: ['@xyflow/vue/style.css'],
});
```
#### Usage
Nodes and edges can come from anywhere you can fetch during SSR, like `useAsyncData` or `useFetch`.
Static data is enough for this example.
There are a few things to pay attention to here:
* Nodes need a `width` and a `height`, otherwise they are rendered hidden until the browser measures them.
* Nodes need `handles`, otherwise their edges don't make it into the HTML at all.
* The server has no container to measure, so `fitView` needs the `width` and `height` props to run there.
```vue filename="app/pages/index.vue"
```
To see what the server actually sent, run `nuxt build && node .output/server/index.mjs` and look at the page source, or turn
JavaScript off in your browser.
#### Node dimensions
Vue Flow measures your nodes in the browser and stores the result in `measured`. There is no layout
engine on the server, so a node without dimensions is rendered with `visibility: hidden` and only
shows up once the client has measured it.
Use `width` and `height` for nodes whose size you decide. Use `initialWidth` and `initialHeight` for
nodes that size themselves from their content: the server uses them for layout and edge paths and
the real measurement takes over after hydration.
#### Handle positions
Edges attach to handles and handle positions come from measuring them. Without them there is no
edge in the HTML, not even an empty path. Declare them with the `handles` property:
```ts
handles: [{ type: 'source', position: Position.Bottom, x: 46, y: 35, width: 8, height: 8 }],
```
`x` and `y` are the top left corner of the handle, not its center, and `width` and `height` default
to `1` if you leave them out. The built-in handle is an 8 by 8 box sitting on the node border, one
pixel inside it, which is where the numbers above come from: on a 100 by 40 node a `Bottom` handle
starts at `x: 46, y: 35` and a `Top` handle at `x: 46, y: -3`.
Declare the same box the browser is going to measure and server and client draw the exact same path. If they differ the edge is
still correct, it just jumps by the difference on the first client render.
#### The viewport
Panning and zooming need a real element, so the pan-zoom instance is only created on the client.
Until then the viewport uses what you declared: `defaultViewport`, or the fit computed from the
`width` and `height` props when you use `fitView`.
Those two props tell the flow what size to assume until it has been measured, which is the frame
`fitView` would otherwise have to measure for itself, so this renders fitted on the server:
```vue
```
They don't size the flow, your CSS still does, so the numbers should match. If the element turns out
to be a different size the client re-fits once it has measured it and you see a small correction,
which is still better than the empty canvas you get without the props. That makes an estimate worth
passing even for a flow that fills the window.
Without them `fitView` has nothing to work with, so it waits for the browser and renders the viewport
with `opacity: 0` until the client has fitted it. The other option is to lay your nodes out near
`0, 0` and leave `fitView` off, which is what the example further up does.
Whichever component creates the store is the one that reads these props, so if you create it yourself
with [``](/api-reference/vue-flow-provider) or `setupVueFlow()`, pass them there. On
a `` inside a provider they're ignored.
#### Client-side only
Not every flow has to be in the HTML. Wrap it in Nuxt's
[``](https://nuxt.com/docs/api/components/client-only) and you can skip all of the above:
```vue
```
For server side rendering outside of Nuxt, like rendering a flow to an HTML string, check out the
[server side rendering guide](/learn/advanced/server-side-rendering).
### Accessibility
If you have suggestions for how we can improve the accessibility of Vue Flow, please
[contact us](https://xyflow.com/contact).
Vue Flow provides keyboard and screen-reader support to help meet accessibility standards. By
default, all nodes and edges are keyboard-focusable and operable. You can toggle these features
with props such as [`nodesFocusable`](/api-reference/vue-flow#nodesfocusable),
[`edgesFocusable`](/api-reference/vue-flow#edgesfocusable), and
[`disableKeyboardA11y`](/api-reference/vue-flow#disablekeyboarda11y), passed to ``:
```vue
```
#### Built-in features
* **Tab navigation:** Pressing `Tab` moves focus through all focusable nodes and edges. These
elements receive `tabindex="0"` and, by default, `role="group"`.
* **Select / deselect:** Press `Enter` or `Space` to select the focused node or edge, and
`Escape` to clear the selection.
* **Move nodes with arrow keys:** If `nodesDraggable` and `nodesFocusable` are both true (the
default), you can move the selected node with the arrow keys. Hold `Shift` to move faster.
Setting `:disable-keyboard-a11y="true"` disables arrow-key movement, while tab-focus and
selection still work.
* **Automatic panning:** When a node receives focus, Vue Flow pans the canvas to bring it into
view. Toggle this with the [`autoPanOnNodeFocus`](/api-reference/vue-flow#autopanonnodefocus)
prop.
* **ARIA descriptions:** Vue Flow adds ARIA descriptions for keyboard guidance, configurable
through [`ariaLabelConfig`](/api-reference/vue-flow#arialabelconfig).
For full keyboard accessibility, keep both `nodesFocusable` and `edgesFocusable` set to
`true`. If either is `false`, those elements won't be keyboard-focusable.
#### ARIA roles for nodes and edges
By default Vue Flow uses semantic ARIA roles for interactive elements. Override a node's role
with the `ariaRole` field:
```ts
const nodes = [
{ id: '1', position: { x: 0, y: 0 }, data: { label: 'Hello' }, ariaRole: 'button' },
];
```
If you don't set a role, `role="group"` is applied. Customizing `ariaRole` lets you match any
relevant role (`'listitem'`, `'region'`, and so on), improving the semantics for assistive
technology.
`ariaRole` is applied to the node wrapper. If a custom node contains interactive elements,
don't set `ariaRole: 'button'` on the node itself. Apply the appropriate role directly to the
interactive element inside.
##### DOM attributes
To pass custom ARIA or other DOM-level attributes (`aria-roledescription`, `data-*`, `tabindex`,
and so on), use the `domAttributes` field. It's available on both nodes and edges:
```ts
const nodes = [
{
id: '2',
position: { x: 0, y: 100 },
data: { label: 'Accessible Node' },
domAttributes: {
'aria-roledescription': 'collapsible node',
'data-test-id': 'node-2',
},
},
];
```
This gives you full control over accessibility-related attributes while keeping Vue Flow's
built-in roles and behavior.
#### Localizing accessibility messages
Vue Flow's built-in accessibility text (keyboard instructions and live updates) can be
customized or localized with the [`ariaLabelConfig`](/api-reference/vue-flow#arialabelconfig)
prop, an object mapping message keys to strings (or functions). The keys are:
| Key | Default value |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `node.a11yDescription.default` | Press enter or space to select a node. Press delete to remove it and escape to cancel. |
| `node.a11yDescription.keyboardDisabled` | Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel. |
| `node.a11yDescription.ariaLiveMessage` | `Moved selected node {direction}. New position, x: {x}, y: {y}` |
| `edge.a11yDescription.default` | Press enter or space to select an edge. You can then press delete to remove it or escape to cancel. |
| `controls.ariaLabel` | Control Panel |
| `controls.zoomIn.ariaLabel` | Zoom In |
| `controls.zoomOut.ariaLabel` | Zoom Out |
| `controls.fitView.ariaLabel` | Fit View |
| `controls.interactive.ariaLabel` | Toggle Interactivity |
| `minimap.ariaLabel` | Mini Map |
| `handle.ariaLabel` | Handle |
For example, to localize the node instructions:
```vue
```
Vue Flow then uses your text instead of the defaults, so screen readers announce messages in
the user's language.
#### WCAG 2.1 AA
Vue Flow provides features that help you meet key WCAG 2.1 AA criteria when implemented
properly:
* **Keyboard:** `Tab` navigation to nodes and edges, interaction with `Enter` / `Space`, and
arrow-key movement for nodes support keyboard operability.
* **Screen reader:** Semantic ARIA roles and labels (`role="group"`, `aria-label`,
`aria-roledescription`) let assistive technology announce nodes and edges meaningfully.
* **ARIA live regions:** Dynamic updates are announced through an `aria-live="assertive"` region
that reports node movements.
* **Instructions and focus management:** Contextual instructions ("Press enter or space to
select a nodeβ¦") plus automatic panning-into-view on focus help satisfy input-assistance
requirements.
See the [ARIA authoring practices](https://www.w3.org/WAI/ARIA/apg/practices/read-me-first/) for
background on ARIA best practices.
### Composables and Providers
Vue Flow ships a set of [composables](/api-reference/composables) and a provider that let you
manage state, reach the flow's methods, and build custom components. The composables read the
flow's store, so that store has to exist above them in the component tree.
#### Providing a store
`` creates the store itself, but you can also create and provide one higher up so that
parents and siblings can reach it. There are two ways to do it, and they do the same thing:
* [`setupVueFlow()`](/api-reference/composables/setup-vue-flow) β a composable you call in a
component's `setup`. It creates the store, provides it to that component's subtree, and
returns the instance right there. This is the idiomatic choice when you own the component that
renders ``.
* [``](/api-reference/vue-flow-provider) β a component you wrap around a
subtree. Reach for it when you want to share one store across several sibling components.
You'll want one of them when:
* a composable such as `useVueFlow` is used outside of ``,
* you need the flow's state or methods from a parent or sibling of ``,
* you render multiple flows on a page (each one scopes its own store), or
* you're working with a client-side router.
```vue filename="App.vue"
```
Or with the provider component wrapping the subtree:
```vue filename="Wrapper.vue"
```
#### `useVueFlow()`
[`useVueFlow()`](/api-reference/composables/use-vue-flow) returns the flow instance and its
methods, so you can read and change nodes, edges, and the viewport from anywhere inside the
store. In the example below a toolbar calls the viewport helpers `zoomIn`, `zoomOut`, and
`fitView`:
Example: learn/composables
##### index.ts
```ts
import { createApp } from 'vue';
import App from './App.vue';
import './index.css';
createApp(App).mount('#app');
```
##### index.html
```html
Vue Flow Example
```
##### xy-extras.css
```css
/*
Extras for the xyflow examples. These styles sit on top of `@xyflow/vue/xy-theme.css`, which has to be
imported before this file. They only add what the library theme doesn't ship with.
*/
.vue-flow__panel {
color: var(--xy-theme-panel-text);
}
.vue-flow__node {
box-shadow: var(--xy-node-boxshadow-default);
}
.vue-flow__node-resizer {
border-radius: 0;
border: none;
}
/*
Custom Example CSS - This CSS is to improve the example experience.
You can remove it if you want to use the default styles.
New Theme Classes:
.xy-theme__button - Styles for buttons.
.xy-theme__input - Styles for text inputs.
.xy-theme__checkbox - Styles for checkboxes.
.xy-theme__select - Styles for dropdown selects.
.xy-theme__label - Styles for labels.
.xy-theme__range - Styles for range sliders (set --range-progress for the filled part).
Use these classes to apply consistent theming across your components.
*/
:root {
--color-primary: var(--xy-theme-primary);
--color-background: light-dark(#fefefe, #1a1b1e);
--color-hover-bg: light-dark(#f6f6f6, #24262c);
--color-disabled: light-dark(#76797e, #8b9099);
--color-primary-muted: color-mix(
in srgb,
var(--color-primary) 40%,
transparent
);
--color-primary-focus: color-mix(
in srgb,
var(--color-primary) 30%,
transparent
);
}
.xy-theme__button-group {
display: flex;
align-items: center;
.xy-theme__button:first-child {
border-radius: 100px 0 0 100px;
}
.xy-theme__button:last-child {
border-radius: 0 100px 100px 0;
margin: 0;
}
}
/* Custom Button Styling */
.xy-theme__button {
display: inline-flex;
align-items: center;
justify-content: center;
height: 2.5rem;
padding: 0 1rem;
border-radius: 100px;
border: 1px solid var(--color-primary);
background-color: var(--color-background);
color: var(--color-primary);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
box-shadow: var(--xy-node-boxshadow-default);
cursor: pointer;
}
.xy-theme__button.active {
background-color: var(--color-primary);
color: white;
border-color: var(--color-primary);
}
.xy-theme__button.active:hover,
.xy-theme__button.active:active {
background-color: var(--color-primary);
opacity: 0.9;
}
.xy-theme__button:hover {
background-color: var(--xy-controls-button-background-color-hover-default);
}
.xy-theme__button:active {
background-color: var(--color-hover-bg);
}
.xy-theme__button:disabled {
color: var(--color-disabled);
opacity: 0.8;
cursor: not-allowed;
border: 1px solid var(--color-disabled);
}
.xy-theme__button > span {
margin-right: 0.2rem;
}
/* Add gap between adjacent buttons */
.xy-theme__button + .xy-theme__button {
margin-left: 0.3rem;
}
/* Example Input Styling */
.xy-theme__input {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 7px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
}
.xy-theme__input:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Specific Checkbox Styling */
.xy-theme__checkbox {
appearance: none;
-webkit-appearance: none;
width: 1.25rem;
height: 1.25rem;
border-radius: 7px;
border: 2px solid var(--color-primary);
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
cursor: pointer;
display: inline-block;
vertical-align: middle;
margin-right: 0.5rem;
}
.xy-theme__checkbox:checked {
background-color: var(--color-primary);
border-color: var(--color-primary);
}
.xy-theme__checkbox:focus {
outline: none;
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Dropdown Styling */
.xy-theme__select {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 50px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
margin-right: 0.5rem;
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__select:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
.xy-theme__label {
margin-top: 10px;
margin-bottom: 3px;
display: inline-block;
color: var(--xy-theme-panel-text);
}
/* Range Slider Styling */
.xy-theme__input[type='range'],
.xy-theme__range {
-webkit-appearance: none;
appearance: none;
display: block;
width: 100%;
height: 0.5rem;
padding: 0;
border: none;
border-radius: 100px;
background: transparent;
cursor: pointer;
}
.xy-theme__input[type='range']:focus,
.xy-theme__range:focus {
outline: none;
box-shadow: none;
}
.xy-theme__input[type='range']::-webkit-slider-runnable-track,
.xy-theme__range::-webkit-slider-runnable-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: linear-gradient(
to right,
var(--color-primary-muted) 0%,
var(--color-primary-muted) var(--range-progress, 0%),
var(--color-hover-bg) var(--range-progress, 0%),
var(--color-hover-bg) 100%
);
}
.xy-theme__input[type='range']::-webkit-slider-thumb,
.xy-theme__range::-webkit-slider-thumb {
-webkit-appearance: none;
appearance: none;
width: 1.25rem;
height: 1.25rem;
margin-top: -0.375rem;
border-radius: 50%;
border: 2px solid var(--color-background);
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-track,
.xy-theme__range::-moz-range-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: var(--color-hover-bg);
}
.xy-theme__input[type='range']::-moz-range-thumb,
.xy-theme__range::-moz-range-thumb {
width: 1.25rem;
height: 1.25rem;
border: none;
border-radius: 50%;
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-progress,
.xy-theme__range::-moz-range-progress {
height: 0.5rem;
border-radius: 100px 0 0 100px;
background: var(--color-primary-muted);
}
```
##### index.css
```css
@import url('./xy-extras.css');
html,
body {
margin: 0;
font-family: sans-serif;
box-sizing: border-box;
}
#app {
width: 100vw;
height: 100vh;
}
.toolbar {
display: flex;
gap: 5px;
}
```
##### App.vue
```vue
```
### Computing Flows
This guide assumes you're familiar with [custom nodes](/learn/customization/custom-nodes) and
the [core concepts](/learn/concepts/terms-and-definitions).
Usually you'd handle your data outside of Vue Flow β on a server or in a store. But you can also
compute data directly inside the graph, updating a node from the data of the nodes connected to
it. This guide builds a small app that mixes a color from three number inputs and decides whether
that color is light or dark.
#### What we're going to build
Three number inputs (red, green, blue) feed a color node, which feeds a "lightness" node that
branches to a log node depending on whether the color is light or dark. Change the inputs and
watch the values flow through:
Example: learn/computing
##### useChannel.ts
```ts
import type { NumberNode } from './types';
import { useNodeConnections, useNodesData } from '@xyflow/vue';
import { computed } from 'vue';
// read the value connected to one of the color node's channel handles
export function useChannel(handleId: string) {
const connections = useNodeConnections({ handleType: 'target', handleId });
const nodeData = useNodesData(
() => connections.value[0]?.source ?? '',
);
return computed(() => nodeData.value?.data.value ?? 0);
}
```
##### types.ts
```ts
import type { Node } from '@xyflow/vue';
export interface RGB {
r: number;
g: number;
b: number;
}
export type NumberNode = Node<{ label: string; value: number }, 'number'>;
export type ColorNode = Node<{ color: RGB }, 'color'>;
export type LightnessNode = Node<
{ light: RGB | null; dark: RGB | null },
'lightness'
>;
export type LogNode = Node, 'log'>;
export type AppNode = NumberNode | ColorNode | LightnessNode | LogNode;
```
##### index.ts
```ts
import { createApp } from 'vue';
import App from './App.vue';
import './index.css';
createApp(App).mount('#app');
```
##### index.html
```html
Vue Flow Example
```
##### xy-extras.css
```css
/*
Extras for the xyflow examples. These styles sit on top of `@xyflow/vue/xy-theme.css`, which has to be
imported before this file. They only add what the library theme doesn't ship with.
*/
.vue-flow__panel {
color: var(--xy-theme-panel-text);
}
.vue-flow__node {
box-shadow: var(--xy-node-boxshadow-default);
}
.vue-flow__node-resizer {
border-radius: 0;
border: none;
}
/*
Custom Example CSS - This CSS is to improve the example experience.
You can remove it if you want to use the default styles.
New Theme Classes:
.xy-theme__button - Styles for buttons.
.xy-theme__input - Styles for text inputs.
.xy-theme__checkbox - Styles for checkboxes.
.xy-theme__select - Styles for dropdown selects.
.xy-theme__label - Styles for labels.
.xy-theme__range - Styles for range sliders (set --range-progress for the filled part).
Use these classes to apply consistent theming across your components.
*/
:root {
--color-primary: var(--xy-theme-primary);
--color-background: light-dark(#fefefe, #1a1b1e);
--color-hover-bg: light-dark(#f6f6f6, #24262c);
--color-disabled: light-dark(#76797e, #8b9099);
--color-primary-muted: color-mix(
in srgb,
var(--color-primary) 40%,
transparent
);
--color-primary-focus: color-mix(
in srgb,
var(--color-primary) 30%,
transparent
);
}
.xy-theme__button-group {
display: flex;
align-items: center;
.xy-theme__button:first-child {
border-radius: 100px 0 0 100px;
}
.xy-theme__button:last-child {
border-radius: 0 100px 100px 0;
margin: 0;
}
}
/* Custom Button Styling */
.xy-theme__button {
display: inline-flex;
align-items: center;
justify-content: center;
height: 2.5rem;
padding: 0 1rem;
border-radius: 100px;
border: 1px solid var(--color-primary);
background-color: var(--color-background);
color: var(--color-primary);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
box-shadow: var(--xy-node-boxshadow-default);
cursor: pointer;
}
.xy-theme__button.active {
background-color: var(--color-primary);
color: white;
border-color: var(--color-primary);
}
.xy-theme__button.active:hover,
.xy-theme__button.active:active {
background-color: var(--color-primary);
opacity: 0.9;
}
.xy-theme__button:hover {
background-color: var(--xy-controls-button-background-color-hover-default);
}
.xy-theme__button:active {
background-color: var(--color-hover-bg);
}
.xy-theme__button:disabled {
color: var(--color-disabled);
opacity: 0.8;
cursor: not-allowed;
border: 1px solid var(--color-disabled);
}
.xy-theme__button > span {
margin-right: 0.2rem;
}
/* Add gap between adjacent buttons */
.xy-theme__button + .xy-theme__button {
margin-left: 0.3rem;
}
/* Example Input Styling */
.xy-theme__input {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 7px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
}
.xy-theme__input:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Specific Checkbox Styling */
.xy-theme__checkbox {
appearance: none;
-webkit-appearance: none;
width: 1.25rem;
height: 1.25rem;
border-radius: 7px;
border: 2px solid var(--color-primary);
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
cursor: pointer;
display: inline-block;
vertical-align: middle;
margin-right: 0.5rem;
}
.xy-theme__checkbox:checked {
background-color: var(--color-primary);
border-color: var(--color-primary);
}
.xy-theme__checkbox:focus {
outline: none;
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Dropdown Styling */
.xy-theme__select {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 50px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
margin-right: 0.5rem;
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__select:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
.xy-theme__label {
margin-top: 10px;
margin-bottom: 3px;
display: inline-block;
color: var(--xy-theme-panel-text);
}
/* Range Slider Styling */
.xy-theme__input[type='range'],
.xy-theme__range {
-webkit-appearance: none;
appearance: none;
display: block;
width: 100%;
height: 0.5rem;
padding: 0;
border: none;
border-radius: 100px;
background: transparent;
cursor: pointer;
}
.xy-theme__input[type='range']:focus,
.xy-theme__range:focus {
outline: none;
box-shadow: none;
}
.xy-theme__input[type='range']::-webkit-slider-runnable-track,
.xy-theme__range::-webkit-slider-runnable-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: linear-gradient(
to right,
var(--color-primary-muted) 0%,
var(--color-primary-muted) var(--range-progress, 0%),
var(--color-hover-bg) var(--range-progress, 0%),
var(--color-hover-bg) 100%
);
}
.xy-theme__input[type='range']::-webkit-slider-thumb,
.xy-theme__range::-webkit-slider-thumb {
-webkit-appearance: none;
appearance: none;
width: 1.25rem;
height: 1.25rem;
margin-top: -0.375rem;
border-radius: 50%;
border: 2px solid var(--color-background);
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-track,
.xy-theme__range::-moz-range-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: var(--color-hover-bg);
}
.xy-theme__input[type='range']::-moz-range-thumb,
.xy-theme__range::-moz-range-thumb {
width: 1.25rem;
height: 1.25rem;
border: none;
border-radius: 50%;
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-progress,
.xy-theme__range::-moz-range-progress {
height: 0.5rem;
border-radius: 100px 0 0 100px;
background: var(--color-primary-muted);
}
```
##### index.css
```css
@import url('./xy-extras.css');
html,
body {
margin: 0;
font-family: sans-serif;
box-sizing: border-box;
}
#app {
width: 100vw;
height: 100vh;
}
.number-input,
.lightness-node,
.log-node {
padding: 10px;
border-radius: 4px;
background: var(--xy-node-background-color-default);
color: var(--xy-node-color-default);
font-size: 12px;
}
.number-input label {
display: block;
margin-bottom: 4px;
}
.number-input input {
width: 60px;
}
.color-node {
width: 90px;
height: 90px;
border-radius: 4px;
display: flex;
align-items: center;
justify-content: center;
}
.color-label {
color: #fff;
mix-blend-mode: difference;
font-size: 11px;
font-family: monospace;
}
```
##### NumberInput.vue
```vue
```
##### Log.vue
```vue
rgb({{ value.r }}, {{ value.g }}, {{ value.b }})
waitingβ¦
```
##### Lightness.vue
```vue
{{ isLight ? 'light' : 'dark' }}
```
##### ColorPreview\.vue
```vue
{{ `rgb(${color.r}, ${color.g}, ${color.b})` }}
```
##### App.vue
```vue
```
#### Reading and writing node data
Two composables do the work:
* [`useNodeConnections`](/api-reference/composables/use-node-connections) tells a node which other
nodes are connected to a given handle.
* [`useNodesData`](/api-reference/composables/use-nodes-data) reads the `data` of those connected
nodes.
And you write to a node's own data with
[`updateNodeData`](/api-reference/composables/use-vue-flow) from `useVueFlow()`.
##### The input node
`NumberInput` keeps its value in local state (writing straight into node data can make the cursor
jump), caps it to 0β255, and mirrors it into the node's `data` on every change:
```vue filename="NumberInput.vue"
```
By default `updateNodeData` merges into the existing `data`. Pass `{ replace: true }` as a second
option to overwrite it instead.
##### Reading connected data
The color node has one target handle per channel. Reading a channel β find the connection, then
read the connected node's data β is a natural composable, so extract it into its own file:
```ts filename="useChannel.ts"
import type { NumberNode } from './types';
import { useNodeConnections, useNodesData } from '@xyflow/vue';
import { computed } from 'vue';
export function useChannel(handleId: string) {
const connections = useNodeConnections({ handleType: 'target', handleId });
const nodeData = useNodesData(() => connections.value[0]?.source ?? '');
return computed(() => nodeData.value?.data.value ?? 0);
}
```
The color node calls it once per channel, computes the color, and writes it back to its own data so
the next node can read it:
```vue filename="ColorPreview.vue"
```
When a node has multiple handles of the same type, give each one an `id` and pass it to
`useNodeConnections` so you read the right connection.
#### Transforming and branching
Because a node's `data` is reactive, you can chain transforms. The `Lightness` node reads the
color, computes its [relative
luminance](https://en.wikipedia.org/wiki/Relative_luminance), and splits the result across two
source handles β writing the color to `light` or `dark` and setting the other to `null`:
```ts
const luminance = computed(() => 0.2126 * color.value.r + 0.7152 * color.value.g + 0.0722 * color.value.b);
const isLight = computed(() => luminance.value >= 128);
watch([color, isLight], () => {
updateNodeData(props.id, {
light: isLight.value ? color.value : null,
dark: isLight.value ? null : color.value,
});
}, { immediate: true });
```
A downstream node then reads only the handle it's connected to, through the connection's
`sourceHandle`. Treating a `null` value as "no data" is a simple way to keep one branch active at
a time:
```ts
const connections = useNodeConnections({ handleType: 'target' });
const sourceData = useNodesData(() => connections.value[0]?.source ?? '');
const sourceHandle = computed(() => connections.value[0]?.sourceHandle ?? '');
const value = computed(() => sourceData.value?.data?.[sourceHandle.value as 'light' | 'dark'] ?? null);
```
#### Summary
To compute data through a flow:
1. store values on a node with [`updateNodeData`](/api-reference/composables/use-vue-flow),
2. find connected nodes with
[`useNodeConnections`](/api-reference/composables/use-node-connections), and
3. read their data with [`useNodesData`](/api-reference/composables/use-nodes-data).
Chain those together to transform data along the way, and branch by treating missing data as a
"stop". Pick one consistent shape for your node data across the whole graph and it stays easy to
reason about.
### Devtools and Debugging
Vue Flow can feel like a black box, but you can reveal a lot about its internal state if you know
where to look. This guide covers the built-in debugging aids, then shows how to build a few small
inspectors of your own.
#### Built-in aids
* **The `debug` prop.** Set [`debug`](/api-reference/vue-flow#debug) on `` and it logs each
event to the console as it fires (high-frequency ones like move, drag, and hover are skipped), so
you can see which events run.
```vue
```
* **The `@error` event.** Vue Flow reports problems as
[`VueFlowError`](/learn/troubleshooting/common-errors) instances through the `@error` event β
listen to it to log them or surface them to the user.
* **Vue Devtools.** Because nodes and edges are ordinary Vue components, the
[Vue Devtools](https://devtools.vuejs.org/) browser extension lets you inspect the component
tree, props, and reactive state of your flow like any other Vue app.
#### Build your own inspectors
Vue Flow doesn't ship a devtools package, but its store is easy to read with `useVueFlow()`. The
example below adds three small inspectors β copy any of them into your own project, they each work
independently:
Example: learn/devtools
##### index.ts
```ts
import { createApp } from 'vue';
import App from './App.vue';
import './index.css';
createApp(App).mount('#app');
```
##### index.html
```html
Vue Flow Example
```
##### xy-extras.css
```css
/*
Extras for the xyflow examples. These styles sit on top of `@xyflow/vue/xy-theme.css`, which has to be
imported before this file. They only add what the library theme doesn't ship with.
*/
.vue-flow__panel {
color: var(--xy-theme-panel-text);
}
.vue-flow__node {
box-shadow: var(--xy-node-boxshadow-default);
}
.vue-flow__node-resizer {
border-radius: 0;
border: none;
}
/*
Custom Example CSS - This CSS is to improve the example experience.
You can remove it if you want to use the default styles.
New Theme Classes:
.xy-theme__button - Styles for buttons.
.xy-theme__input - Styles for text inputs.
.xy-theme__checkbox - Styles for checkboxes.
.xy-theme__select - Styles for dropdown selects.
.xy-theme__label - Styles for labels.
.xy-theme__range - Styles for range sliders (set --range-progress for the filled part).
Use these classes to apply consistent theming across your components.
*/
:root {
--color-primary: var(--xy-theme-primary);
--color-background: light-dark(#fefefe, #1a1b1e);
--color-hover-bg: light-dark(#f6f6f6, #24262c);
--color-disabled: light-dark(#76797e, #8b9099);
--color-primary-muted: color-mix(
in srgb,
var(--color-primary) 40%,
transparent
);
--color-primary-focus: color-mix(
in srgb,
var(--color-primary) 30%,
transparent
);
}
.xy-theme__button-group {
display: flex;
align-items: center;
.xy-theme__button:first-child {
border-radius: 100px 0 0 100px;
}
.xy-theme__button:last-child {
border-radius: 0 100px 100px 0;
margin: 0;
}
}
/* Custom Button Styling */
.xy-theme__button {
display: inline-flex;
align-items: center;
justify-content: center;
height: 2.5rem;
padding: 0 1rem;
border-radius: 100px;
border: 1px solid var(--color-primary);
background-color: var(--color-background);
color: var(--color-primary);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
box-shadow: var(--xy-node-boxshadow-default);
cursor: pointer;
}
.xy-theme__button.active {
background-color: var(--color-primary);
color: white;
border-color: var(--color-primary);
}
.xy-theme__button.active:hover,
.xy-theme__button.active:active {
background-color: var(--color-primary);
opacity: 0.9;
}
.xy-theme__button:hover {
background-color: var(--xy-controls-button-background-color-hover-default);
}
.xy-theme__button:active {
background-color: var(--color-hover-bg);
}
.xy-theme__button:disabled {
color: var(--color-disabled);
opacity: 0.8;
cursor: not-allowed;
border: 1px solid var(--color-disabled);
}
.xy-theme__button > span {
margin-right: 0.2rem;
}
/* Add gap between adjacent buttons */
.xy-theme__button + .xy-theme__button {
margin-left: 0.3rem;
}
/* Example Input Styling */
.xy-theme__input {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 7px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
}
.xy-theme__input:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Specific Checkbox Styling */
.xy-theme__checkbox {
appearance: none;
-webkit-appearance: none;
width: 1.25rem;
height: 1.25rem;
border-radius: 7px;
border: 2px solid var(--color-primary);
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
cursor: pointer;
display: inline-block;
vertical-align: middle;
margin-right: 0.5rem;
}
.xy-theme__checkbox:checked {
background-color: var(--color-primary);
border-color: var(--color-primary);
}
.xy-theme__checkbox:focus {
outline: none;
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Dropdown Styling */
.xy-theme__select {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 50px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
margin-right: 0.5rem;
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__select:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
.xy-theme__label {
margin-top: 10px;
margin-bottom: 3px;
display: inline-block;
color: var(--xy-theme-panel-text);
}
/* Range Slider Styling */
.xy-theme__input[type='range'],
.xy-theme__range {
-webkit-appearance: none;
appearance: none;
display: block;
width: 100%;
height: 0.5rem;
padding: 0;
border: none;
border-radius: 100px;
background: transparent;
cursor: pointer;
}
.xy-theme__input[type='range']:focus,
.xy-theme__range:focus {
outline: none;
box-shadow: none;
}
.xy-theme__input[type='range']::-webkit-slider-runnable-track,
.xy-theme__range::-webkit-slider-runnable-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: linear-gradient(
to right,
var(--color-primary-muted) 0%,
var(--color-primary-muted) var(--range-progress, 0%),
var(--color-hover-bg) var(--range-progress, 0%),
var(--color-hover-bg) 100%
);
}
.xy-theme__input[type='range']::-webkit-slider-thumb,
.xy-theme__range::-webkit-slider-thumb {
-webkit-appearance: none;
appearance: none;
width: 1.25rem;
height: 1.25rem;
margin-top: -0.375rem;
border-radius: 50%;
border: 2px solid var(--color-background);
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-track,
.xy-theme__range::-moz-range-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: var(--color-hover-bg);
}
.xy-theme__input[type='range']::-moz-range-thumb,
.xy-theme__range::-moz-range-thumb {
width: 1.25rem;
height: 1.25rem;
border: none;
border-radius: 50%;
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-progress,
.xy-theme__range::-moz-range-progress {
height: 0.5rem;
border-radius: 100px 0 0 100px;
background: var(--color-primary-muted);
}
```
##### index.css
```css
@import url('./xy-extras.css');
html,
body {
margin: 0;
font-family: sans-serif;
box-sizing: border-box;
}
#app {
width: 100vw;
height: 100vh;
}
.logger {
font-family: monospace;
font-size: 11px;
background: var(--xy-theme-panel-bg, #fff);
color: var(--xy-theme-panel-text, #111);
padding: 6px 8px;
border-radius: 4px;
}
.node-inspector {
position: absolute;
top: 0;
left: 0;
font-family: monospace;
font-size: 9px;
line-height: 1.35;
background: rgba(0, 0, 0, 0.75);
color: #fff;
padding: 3px 5px;
border-radius: 3px;
pointer-events: none;
white-space: nowrap;
}
.devtools {
display: flex;
padding: 0;
}
.devtools button {
border: none;
border-right: 1px solid var(--xy-theme-subtle-border, #ddd);
padding: 5px 15px;
font-family: monospace;
font-size: 12px;
font-weight: bold;
cursor: pointer;
background: var(--xy-theme-panel-bg, #fff);
color: var(--xy-theme-panel-text, #222);
}
.devtools button:first-child {
border-radius: 4px 0 0 4px;
}
.devtools button:last-child {
border-right: none;
border-radius: 0 4px 4px 0;
}
.devtools button.active,
.devtools button:hover {
background: rgb(238, 58, 115);
color: #fff;
}
```
##### ViewportLogger.vue
```vue
x: {{ viewport.x.toFixed(1) }} Β· y: {{ viewport.y.toFixed(1) }} Β· zoom:
{{ viewport.zoom.toFixed(2) }}
```
##### NodeInspector.vue
```vue
```
##### App.vue
```vue
```
##### Viewport logger
The simplest thing to pull from the store is the viewport. `useVueFlow().viewport` is a
`{ x, y, zoom }` object derived from the pane transform; render it into a
[``](/api-reference/components/panel):
```vue filename="ViewportLogger.vue"
x: {{ viewport.x.toFixed(1) }} Β· y: {{ viewport.y.toFixed(1) }} Β· zoom: {{ viewport.zoom.toFixed(2) }}
```
##### Change logger
Every change Vue Flow makes to your nodes flows through the `onNodesChange` hook. Subscribe to it
to log each batch as it's dispatched β a great way to see what Vue Flow does under the hood:
```vue filename="ChangeLogger.vue"
{{ entry }}
```
See the [`NodeChange`](/api-reference/types/node-change) and
[`EdgeChange`](/api-reference/types/edge-change) types for everything a change can be.
##### Node inspector
To render debug info that pans and zooms along with the flow, use the `#zoom-pane` slot β content
there lives inside the transformed viewport, so you can position it in flow coordinates. Here we
read every node with `useVueFlow().getNodes` and render its id and type above it:
```vue filename="NodeInspector.vue"
id: {{ node.id }}
type: {{ node.type ?? 'default' }}
```
Render it through the slot on ``:
```vue filename="App.vue"
```
The `#zoom-pane` slot is Vue Flow's way to render into the viewport: its content is positioned and
transformed along with the nodes and edges as the user pans and zooms.
### Multiplayer
Node-based UIs are often visual and explorative in nature. For collaborative features that
usually means there's no satisfying "middle-ground" like sparsely syncing state between users,
because it would break visual consistency or make collaborative exploration more complicated.
Often a full live multiplayer system needs to be put in place. This guide explores best practices
for adding realtime multiplayer collaboration to a Vue Flow application with a sync engine such as
[Yjs](https://github.com/yjs/yjs).
#### What are multiplayer applications?
Although **realtime collaboration** would be the correct term, we refer to it as **multiplayer**,
which was most likely popularized in this context by Figma. Besides being more intuitive, it also
does a better job of communicating the commitment to something truly realtime by putting it in the
same category as competitive video games.
To figure out what degree of collaboration your application supports, look at how closely it
resembles a multiplayer game. Those features likely include:
* No manual saving is required; all users share a world where actions are persisted.
* Any change made by another user is immediately visible to you.
* Not only completed actions but transitive states are synced too (dragging a node, not only
dropping it).
* You can see other users (their cursors or viewport positions).
##### A word of caution
Making multiplayer applications is hard. When users collaboratively edit shared objects,
conflicts, delays, connection drops, and concurrent operations are all expected. The hardest
challenge is **conflict resolution**: you need a sync engine that can merge changes coming from the
server (or other clients) into the (often optimistic) client state, handle conflicts and
disconnects gracefully, and provide a reliable network layer.
The simplest sync engine would be "first come, first served", with failed requests ignored. Try to
handle this by hand and a wide variety of edge cases emerge: networks are slow, clients
disconnect, and the order of actions matters.
##### Local-first and CRDTs
Depending on how far you take conflict and disconnect handling, you quickly land in
**local-first** territory. When your sync engine lets a user stay disconnected for an indefinite
amount of time, you have a local-first application. For a good primer, we recommend
[Ink & Switch's essay](https://www.inkandswitch.com/essay/local-first/) that coined the term.
A **CRDT** (*Conflict-free Replicated Data Type*) is a data structure that lets multiple users edit
the same data simultaneously on different devices, then automatically merges all changes without
conflicts β no central server needed. Rather than storing only the current value, CRDTs keep the
operation history on every connected client, so any replica can merge changes into the same final
state regardless of the order updates arrive. A couple of popular solutions are
[Yjs](https://github.com/yjs/yjs), [Automerge](https://automerge.org/), and [Loro](https://loro.dev).
#### What Vue Flow state should I sync?
Among your first considerations is **how** you want to sync **what** parts of your app's local
state.
##### Ephemeral vs durable
There are many ways to sync state between clients, but they fall into two groups: ephemeral and
durable (atomic) changes. **Ephemeral changes are not persisted**, and neither their consistency
nor their correctness is very important β things like cursor or viewport positions, or transient
interaction state. Missing some of these updates won't break anything; after a connection loss a
client can just listen for the newest changes and restore any lost state.
**Updates to the nodes and edges, on the other hand, should be persistent and consistent.** Imagine
Alice deletes a node and Bob misses the update β now if Bob moves that node, the application state
is inconsistent. This kind of data needs a solution that handles disconnects more aggressively and
can discard impossible actions like moving a deleted node.
At the core of a multiplayer Vue Flow app is syncing the nodes and edges. But not all of their
state should be synced: which nodes and edges are selected should differ per client, and some
fields are computed or transient (`dragging`, `resizing`, `measured`). Here's an overview of what
to sync and what not to.
##### Nodes
| Field | Durable | Ephemeral | Explanation |
| ----------------- | ------- | --------- | ------------------------------------- |
| `id` | β | β | Important, always needs to be in sync |
| `type` | β | β | Important, always needs to be in sync |
| `data` | β | β | Important, always needs to be in sync |
| `position` | β | β³οΈ | Important, includes transient state |
| `width`, `height` | β | β³οΈ | Important, includes transient state |
| `dragging` | β | β | Transient interaction state |
| `resizing` | β | β | Transient interaction state |
| `selected` | β | β | Per-user UI state |
| `measured` | β | β | Computed from the DOM |
##### Edges
| Field | Durable | Ephemeral | Explanation |
| -------------- | ------- | --------- | ------------------------------------- |
| `id` | β | β | Important, always needs to be in sync |
| `type` | β | β | Important, always needs to be in sync |
| `data` | β | β | Important, always needs to be in sync |
| `source` | β | β | Important, always needs to be in sync |
| `target` | β | β | Important, always needs to be in sync |
| `sourceHandle` | β | β | Important, always needs to be in sync |
| `targetHandle` | β | β | Important, always needs to be in sync |
| `selected` | β | β | Per-user UI state |
##### Connections and cursors
Good examples of ephemeral data are
[connections](/api-reference/composables/use-connection) (the transient part of an edge being
created) and cursors.
Sharing each user's connection status improves visual consistency across clients, but losing it on
disconnect doesn't affect the correctness of the shared data β it's purely presentational. The same
goes for cursors: they help create the immersion of a shared workspace, but they aren't essential
to the app's integrity. As long as the nodes and edges stay in sync, cursor state can be safely
discarded.
Both can be shared as purely ephemeral state. To reduce the frequency of live updates you can
debounce them, and smooth other users' cursor movements with a library like
[perfect-cursors](https://github.com/steveruizok/perfect-cursors).
#### Third-party libraries and services
There's no one-size-fits-all backend. The choice between CRDT-based local-first libraries (like
[Yjs](https://yjs.dev/) and [Jazz](https://jazz.tools)) and server-authoritative approaches (like
[Liveblocks](https://liveblocks.io/), [Supabase](https://supabase.com/), and
[Convex](https://convex.dev/)) shapes how you build:
* **CRDT libraries** make offline-first multiplayer easier, with automatic conflict resolution for
free. But if your app is also structured around a database, you'll need to write your own
adapters between the CRDT library and the database.
* **Server-authoritative solutions** are easier to pair with a database and classical application
logic, but complicate offline-first support, conflict resolution, and development.
| Name | Architecture | Offline support | Conflict resolution | Notes |
| ---------------------------------------- | ------------------------------- | -------------------------- | ------------------------- | ------------------------------------------------------------------------------------------- |
| [**Yjs**](https://yjs.dev/) | CRDT (local-first) | β Full offline support | Automatic (CRDT) | Collaborative editing, offline-first CRDT for local-first apps. |
| [**Jazz**](https://jazz.tools/) | CRDT (local-first) | β Full offline support | Automatic (CRDT) | A full, offline-first database solution that handles multiplayer natively. |
| [**Liveblocks**](https://liveblocks.io/) | Server-authoritative, CRDT-like | π‘ Partial offline support | Uses CRDTs under the hood | Real-time collaboration platform with an open-source backend. |
| [**Supabase**](https://supabase.com/) | Server-authoritative | β Requires connection | Manual / RLS policies | Classic SQL-based database with realtime support, but no CRDT (resolve conflicts manually). |
| [**Convex**](https://convex.dev/) | Server-authoritative | β Requires connection | Optimistic | TypeScript-first database with real-time queries and a sync engine. |
| [**Automerge**](https://automerge.org/) | CRDT (local-first) | β Full offline support | Automatic (CRDT) | The canonical CRDT library; can be paired with a database like Convex. |
| [**Loro**](https://loro.dev/) | CRDT (local-first) | β Full offline support | Automatic (CRDT) | A fast CRDT library in Rust and WebAssembly with history tracking and version control. |
### Performance
When you're dealing with a large number of nodes or complex custom components, performance can
become challenging. Here are a few effective strategies to keep Vue Flow fast.
#### Keep reactivity shallow
The most common source of performance problems is unnecessary reactivity. Node drags, pans, and
zooms all update state frequently, so the cost of each update matters.
Store your `nodes` and `edges` in a
[`shallowRef`](https://vuejs.org/api/reactivity-advanced.html#shallowref) rather than a deep
`ref`, and replace the whole array when you change it (for example with
`Array.prototype.map`) instead of mutating individual nodes. A deep `ref` makes every property
of every node reactive, which is expensive for large flows and buys you nothing here, because
Vue Flow tracks changes at the array level.
```ts
import type { Node } from '@xyflow/vue';
import { shallowRef } from 'vue';
// one dependency for the whole array
const nodes = shallowRef([/* ... */]);
// update by replacing, not mutating
nodes.value = nodes.value.map(n => (n.id === '1' ? { ...n, selected: true } : n));
```
With `v-model:nodes` / `v-model:edges`, Vue Flow already replaces the whole array when it
applies a change, so a `shallowRef` is all you need. See
[Adding Interactivity](/learn/concepts/adding-interactivity).
#### Memoize expensive custom nodes
Custom nodes and edges are ordinary Vue components, so Vue only re-renders them when their props
change. If a custom node has an expensive template that depends on only a few props, you can
skip re-rendering while those props are unchanged with
[`v-memo`](https://vuejs.org/api/built-in-directives.html#v-memo):
```vue
```
Unlike React, you don't need to wrap handlers or option objects such as `defaultEdgeOptions` and
`snapGrid` in anything: `
```
Instead, read only what you need through a targeted composable such as
[`useNodesData`](/api-reference/composables/use-nodes-data) or
[`useNodeConnections`](/api-reference/composables/use-node-connections), so the component reacts
only when that specific data changes:
```vue
```
#### Collapse large node trees
If your graph is deeply nested, rendering every node at once is wasteful. Render a limited set
and let users expand on demand by toggling each node's `hidden` field with
[`updateNode`](/api-reference/composables/use-vue-flow):
```ts
import { useVueFlow } from '@xyflow/vue';
const { updateNode } = useVueFlow();
function toggleChildren(node) {
for (const childId of node.data.children ?? []) {
updateNode(childId, prev => ({ hidden: !prev.hidden }));
}
}
```
Hiding nodes until they're expanded keeps the rendered graph small without losing any state.
#### Simplify node and edge styles
If you've optimized everything else and large graphs still feel sluggish, look at your CSS.
Complex styles, especially animations, gradients, and box-shadows, are re-rasterized by the
browser on every frame while panning and zooming, which can dominate the frame budget.
A heavy, multi-layer blurred `box-shadow` on nodes is a frequent culprit: it looks fine when
static but hurts pan and zoom smoothness on large flows in Chromium. Prefer a light,
single-layer shadow or a `border` for nodes you render in bulk.
#### See it at scale
The [stress test example](/examples/nodes/stress) renders a large graph you can pan and zoom to
feel these trade-offs in practice.
### Server Side Rendering
### Server side rendering, server side generation
This is an advanced use case and assumes you are already familiar with Vue Flow. If you're new to Vue Flow, check out our [getting started guide](/learn).
In this guide, you'll learn how to configure Vue Flow for server-side rendering, enabling you to:
* Generate static HTML diagrams for documentation
* Render Vue Flow diagrams in non-JavaScript environments
* Create dynamic Open Graph images for social media sharing
##### Why Server-Side Rendering is Complex
To understand why server-side rendering in Vue Flow requires special configuration, let's look at what Vue Flow typically handles on the client side:
1. **Node Dimension Calculation**
* Nodes can contain any content, so their dimensions are determined by the browser's layout engine
* This dynamic sizing isn't available during server-side rendering
2. **Handle Position Detection**
* Edge connections require precise handle positions
* These positions are calculated based on CSS layout, which isn't available on the server
3. **Container Size Adaptation**
* Vue Flow adapts to its container's dimensions
* Server-side rendering needs an explicit viewport
##### Node Dimensions
The most crucial aspect of server-side rendering is specifying node dimensions. On the client, Vue Flow automatically measures nodes and stores dimensions in `measured.width` and `measured.height`. For server-side rendering, you must provide these dimensions explicitly using either:
Node Dimension Options:
1. `width` and `height`: Static dimensions that won't change
2. `initialWidth` and `initialHeight`: Dynamic dimensions that may change after client-side hydration
```ts
import type { Node } from '@xyflow/vue';
const nodes: Node[] = [
{
id: '1',
type: 'default',
position: { x: 0, y: 0 },
data: { label: 'Node 1' },
width: 100,
height: 50,
},
];
```
##### Handle Positions
To render edges on the server, you need to provide handle positions explicitly. On the client, Vue Flow calculates these positions automatically, but for server-side rendering, you must specify them using the `handles` property:
```ts
import type { Node } from '@xyflow/vue';
import { Position } from '@xyflow/vue';
const nodes: Node[] = [
{
id: '1',
type: 'default',
position: { x: 0, y: 0 },
data: { label: 'Node 1' },
width: 100,
height: 50,
handles: [
{
type: 'target',
position: Position.Top,
x: 100 / 2,
y: 0,
},
{
type: 'source',
position: Position.Bottom,
x: 100 / 2,
y: 50,
},
],
},
];
```
##### Setting the viewport for Server-Side Rendering
Vue Flow normally takes its size from the element it's in, which is something the server can't
measure. The `width` and `height` props tell it what size to assume until it can, and that's enough
for `fitView` to compute a transform before anything is rendered:
```vue
```
The props don't size the element, that's still your CSS, so the two should agree. If they don't, the
server renders the fit you declared and the client re-fits to the real size after measuring it, which
shows up as a small jump. For a flow that fills a responsive container an estimate is still worth
passing: a roughly right first paint beats an empty one.
Without the props `fitView` has to wait for the browser and renders the viewport with `opacity: 0`
until the client has fitted it, so the server output is an empty canvas. In that case position your
nodes near `0, 0` and leave `fitView` off, or set
[`defaultViewport`](/api-reference/vue-flow) to the transform you want the server to render.
Whichever component creates the store reads these props, so with a
[``](/api-reference/vue-flow-provider) they belong on the provider. On a ``
inside one they're ignored.
##### Generating Static HTML
To create static HTML output, you can use Vue's server renderer. This generates an HTML string that you can use for static files or HTTP responses:
```vue filename="Flow.vue"
```
```ts
import { createSSRApp } from 'vue';
import { renderToString } from 'vue/server-renderer';
import Flow from './Flow.vue';
async function toHTML({ nodes, edges }) {
const app = createSSRApp(Flow, { nodes, edges });
return await renderToString(app);
}
```
### State Management
This guide assumes you're familiar with [custom nodes](/learn/customization/custom-nodes) and
the [core concepts](/learn/concepts/terms-and-definitions).
As your app grows, you often need to update the graph from inside a node β a color picker that
recolors its own node, say. In React Flow you'd reach for a state library like Zustand to do
this. In Vue Flow you usually don't have to.
#### You already have a store: `useVueFlow()`
`useVueFlow()` returns the same flow instance from anywhere inside `` (or a
``), so a custom node can read and update the graph directly, with no external
library and no callbacks threaded through `data`. To recolor a node from within it, call
[`updateNodeData`](/api-reference/composables/use-vue-flow):
```vue filename="ColorChooserNode.vue"
```
The `nodrag` class stops the node from being dragged while the user interacts with the input.
Example: learn/state-management
##### index.ts
```ts
import { createApp } from 'vue';
import App from './App.vue';
import './index.css';
createApp(App).mount('#app');
```
##### index.html
```html
Vue Flow Example
```
##### xy-extras.css
```css
/*
Extras for the xyflow examples. These styles sit on top of `@xyflow/vue/xy-theme.css`, which has to be
imported before this file. They only add what the library theme doesn't ship with.
*/
.vue-flow__panel {
color: var(--xy-theme-panel-text);
}
.vue-flow__node {
box-shadow: var(--xy-node-boxshadow-default);
}
.vue-flow__node-resizer {
border-radius: 0;
border: none;
}
/*
Custom Example CSS - This CSS is to improve the example experience.
You can remove it if you want to use the default styles.
New Theme Classes:
.xy-theme__button - Styles for buttons.
.xy-theme__input - Styles for text inputs.
.xy-theme__checkbox - Styles for checkboxes.
.xy-theme__select - Styles for dropdown selects.
.xy-theme__label - Styles for labels.
.xy-theme__range - Styles for range sliders (set --range-progress for the filled part).
Use these classes to apply consistent theming across your components.
*/
:root {
--color-primary: var(--xy-theme-primary);
--color-background: light-dark(#fefefe, #1a1b1e);
--color-hover-bg: light-dark(#f6f6f6, #24262c);
--color-disabled: light-dark(#76797e, #8b9099);
--color-primary-muted: color-mix(
in srgb,
var(--color-primary) 40%,
transparent
);
--color-primary-focus: color-mix(
in srgb,
var(--color-primary) 30%,
transparent
);
}
.xy-theme__button-group {
display: flex;
align-items: center;
.xy-theme__button:first-child {
border-radius: 100px 0 0 100px;
}
.xy-theme__button:last-child {
border-radius: 0 100px 100px 0;
margin: 0;
}
}
/* Custom Button Styling */
.xy-theme__button {
display: inline-flex;
align-items: center;
justify-content: center;
height: 2.5rem;
padding: 0 1rem;
border-radius: 100px;
border: 1px solid var(--color-primary);
background-color: var(--color-background);
color: var(--color-primary);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
box-shadow: var(--xy-node-boxshadow-default);
cursor: pointer;
}
.xy-theme__button.active {
background-color: var(--color-primary);
color: white;
border-color: var(--color-primary);
}
.xy-theme__button.active:hover,
.xy-theme__button.active:active {
background-color: var(--color-primary);
opacity: 0.9;
}
.xy-theme__button:hover {
background-color: var(--xy-controls-button-background-color-hover-default);
}
.xy-theme__button:active {
background-color: var(--color-hover-bg);
}
.xy-theme__button:disabled {
color: var(--color-disabled);
opacity: 0.8;
cursor: not-allowed;
border: 1px solid var(--color-disabled);
}
.xy-theme__button > span {
margin-right: 0.2rem;
}
/* Add gap between adjacent buttons */
.xy-theme__button + .xy-theme__button {
margin-left: 0.3rem;
}
/* Example Input Styling */
.xy-theme__input {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 7px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
}
.xy-theme__input:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Specific Checkbox Styling */
.xy-theme__checkbox {
appearance: none;
-webkit-appearance: none;
width: 1.25rem;
height: 1.25rem;
border-radius: 7px;
border: 2px solid var(--color-primary);
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
cursor: pointer;
display: inline-block;
vertical-align: middle;
margin-right: 0.5rem;
}
.xy-theme__checkbox:checked {
background-color: var(--color-primary);
border-color: var(--color-primary);
}
.xy-theme__checkbox:focus {
outline: none;
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Dropdown Styling */
.xy-theme__select {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 50px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
margin-right: 0.5rem;
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__select:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
.xy-theme__label {
margin-top: 10px;
margin-bottom: 3px;
display: inline-block;
color: var(--xy-theme-panel-text);
}
/* Range Slider Styling */
.xy-theme__input[type='range'],
.xy-theme__range {
-webkit-appearance: none;
appearance: none;
display: block;
width: 100%;
height: 0.5rem;
padding: 0;
border: none;
border-radius: 100px;
background: transparent;
cursor: pointer;
}
.xy-theme__input[type='range']:focus,
.xy-theme__range:focus {
outline: none;
box-shadow: none;
}
.xy-theme__input[type='range']::-webkit-slider-runnable-track,
.xy-theme__range::-webkit-slider-runnable-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: linear-gradient(
to right,
var(--color-primary-muted) 0%,
var(--color-primary-muted) var(--range-progress, 0%),
var(--color-hover-bg) var(--range-progress, 0%),
var(--color-hover-bg) 100%
);
}
.xy-theme__input[type='range']::-webkit-slider-thumb,
.xy-theme__range::-webkit-slider-thumb {
-webkit-appearance: none;
appearance: none;
width: 1.25rem;
height: 1.25rem;
margin-top: -0.375rem;
border-radius: 50%;
border: 2px solid var(--color-background);
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-track,
.xy-theme__range::-moz-range-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: var(--color-hover-bg);
}
.xy-theme__input[type='range']::-moz-range-thumb,
.xy-theme__range::-moz-range-thumb {
width: 1.25rem;
height: 1.25rem;
border: none;
border-radius: 50%;
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-progress,
.xy-theme__range::-moz-range-progress {
height: 0.5rem;
border-radius: 100px 0 0 100px;
background: var(--color-primary-muted);
}
```
##### index.css
```css
@import url('./xy-extras.css');
html,
body {
margin: 0;
font-family: sans-serif;
box-sizing: border-box;
}
#app {
width: 100vw;
height: 100vh;
}
.color-chooser-node {
padding: 20px;
border-radius: 5px;
}
.color-chooser-node input {
cursor: pointer;
}
```
##### ColorChooserNode.vue
```vue
```
##### App.vue
```vue
```
#### When you want an external store: Pinia
Reach for [Pinia](https://pinia.vuejs.org/) when the graph is part of larger app state, or when
components outside the flow need to read or change it. Keep the `nodes` and `edges` in the store
and expose actions to mutate them:
```ts filename="stores/flow.ts"
import type { Edge, Node } from '@xyflow/vue';
import { defineStore } from 'pinia';
import { shallowRef } from 'vue';
export const useFlowStore = defineStore('flow', () => {
const nodes = shallowRef([/* ... */]);
const edges = shallowRef([/* ... */]);
function updateNodeColor(id: string, color: string) {
// replace the array so Vue Flow sees the change
nodes.value = nodes.value.map(n =>
n.id === id ? { ...n, data: { ...n.data, color } } : n,
);
}
return { nodes, edges, updateNodeColor };
});
```
Bind the store's arrays to `` with `v-model` and Vue Flow keeps them in sync as the user
drags, selects, and connects:
```vue filename="App.vue"
```
Any component can now call `useFlowStore().updateNodeColor(id, color)` and the flow updates. If
you'd rather inspect or intercept every change before it's applied, drop `v-model` and use the
[controlled flow](/learn/concepts/adding-interactivity#controlled-flow) pattern with
`@nodes-change` / `@edges-change` instead.
### Testing
There are plenty of ways to test a Vue application. For a Vue Flow app we recommend
[Cypress](https://www.cypress.io/) or [Playwright](https://playwright.dev/): Vue Flow measures
nodes in order to render edges, and that relies on real DOM elements, which a headless browser
provides.
#### Using Cypress or Playwright
No extra setup is needed. See the getting-started guides for
[Cypress](https://docs.cypress.io/guides/getting-started/installing-cypress) and
[Playwright](https://playwright.dev/docs/intro).
#### Using Vitest
[Vitest](https://vitest.dev/) runs in a simulated DOM (jsdom or happy-dom) that doesn't implement
the layout APIs Vue Flow relies on, so you need to shim them. Add this helper and call
`mockVueFlow()` in a setup file (or a `beforeEach`):
```ts filename="mockVueFlow.ts"
// A jsdom/happy-dom-friendly stand-in for the ResizeObserver and DOMMatrixReadOnly APIs
// Vue Flow uses to measure nodes and read the viewport transform.
class ResizeObserver {
callback: globalThis.ResizeObserverCallback;
constructor(callback: globalThis.ResizeObserverCallback) {
this.callback = callback;
}
observe(target: Element) {
setTimeout(() => {
this.callback([{ target } as globalThis.ResizeObserverEntry], this);
}, 0);
}
unobserve() {}
disconnect() {}
}
class DOMMatrixReadOnly {
m22: number;
constructor(transform: string) {
const scale = transform?.match(/scale\(([1-9.])\)/)?.[1];
this.m22 = scale !== undefined ? +scale : 1;
}
}
let init = false;
export function mockVueFlow() {
if (init) {
return;
}
init = true;
global.ResizeObserver = ResizeObserver as unknown as typeof globalThis.ResizeObserver;
global.DOMMatrixReadOnly = DOMMatrixReadOnly as unknown as typeof globalThis.DOMMatrixReadOnly;
Object.defineProperties(global.HTMLElement.prototype, {
offsetHeight: {
get() {
return Number.parseFloat(this.style.height) || 1;
},
},
offsetWidth: {
get() {
return Number.parseFloat(this.style.width) || 1;
},
},
});
(global.SVGElement.prototype as unknown as { getBBox: () => DOMRect }).getBBox = () =>
({ x: 0, y: 0, width: 0, height: 0 }) as DOMRect;
}
```
Register it as a Vitest setup file:
```ts filename="vitest.config.ts"
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vitest/config';
export default defineConfig({
plugins: [vue()],
test: {
environment: 'jsdom',
setupFiles: ['./mockVueFlow.ts'],
},
});
```
##### Testing edges
Edges only render once their nodes have been measured, so mount inside a sized container and
wait for them with `vi.waitFor`:
```ts filename="flow.test.ts"
import { mount } from '@vue/test-utils';
import { VueFlow } from '@xyflow/vue';
import { expect, test, vi } from 'vitest';
import { mockVueFlow } from './mockVueFlow';
mockVueFlow();
test('renders edges', async () => {
const wrapper = mount(VueFlow, {
attrs: { style: 'width: 800px; height: 600px' },
props: { nodes, edges },
});
await vi.waitFor(() => {
expect(wrapper.findAll('.vue-flow__edge').length).toBeGreaterThan(0);
});
});
```
To test mouse events inside a custom node with Vitest, disable dragging and panning so
`d3-drag` β which needs a real browser β stays out of the way:
```vue
```
### Usage with TypeScript
Vue Flow is written in TypeScript because we value the additional safety barrier it provides.
We export all the types you need for correctly typing data structures and functions you pass to the Vue Flow component. We also provide a way to extend the types of nodes and edges.
#### Basic Usage
Let's start with the essential types needed for a basic implementation. While TypeScript can infer some types automatically, we'll define them explicitly for clarity.
```vue
```
##### Custom Nodes
When working with [custom nodes](/learn/customization/custom-nodes), you can extend the base `Node` type to include your custom data and pass it to `NodeProps` as a generic. It's a good idea to keep these types in a shared `types.ts` so you can reuse them:
```ts filename="types.ts"
import type { Node } from '@xyflow/vue';
export type NumberNode = Node<{ number: number }, 'number'>;
```
When defining node data, you must use a `type` alias (interfaces won't satisfy the
`Record` constraint on node data).
```vue filename="NumberNode.vue"
A special number: {{ data.number }}
```
For a single custom node that renders different content based on the node type, use a union
type and narrow on `type`:
```vue filename="CustomNode.vue"
A special number: {{ props.data.number }}
A special text: {{ props.data.text }}
```
Vue templates do not narrow `props.data` from a `props.type` check; for strict type safety,
narrow in `
```
#### Advanced Usage
In complex applications, you'll likely have multiple custom nodes and edges with different data structures. When using built-in functions and composables, you'll need to properly [narrow down](https://www.typescriptlang.org/docs/handbook/2/narrowing.html) the types to prevent runtime errors.
##### `Node` and `Edge` Type Unions
Many functions, callbacks, and composables (including the `` component) accept `NodeType` or `EdgeType` generics. These are unions of all your custom node and edge types. As long as you've properly typed your data objects, you can reuse their exported types, typically from a shared `types.ts`:
If you're using any built-in nodes (`'input'`, `'output'`, `'default'`, `'group'`), include
the `BuiltInNode` type from `@xyflow/vue` in your node union. Built-in edges are already
covered by the base `Edge` type.
```ts filename="types.ts"
import type { BuiltInNode, Edge, Node } from '@xyflow/vue';
export type NumberNode = Node<{ number: number }, 'number'>;
export type TextNode = Node<{ text: string }, 'text'>;
export type CustomEdge = Edge<{ value: number }, 'custom'>;
export type AppNode = BuiltInNode | NumberNode | TextNode;
export type AppEdge = Edge | CustomEdge;
```
You then register the components through the `#node-` / `#edge-` slots and bind
your typed arrays:
```vue filename="App.vue"
```
##### Composables
You can use these type unions to properly type the return values of composables:
```vue
```
##### Type Guards
TypeScript provides several ways to implement [type guards](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#typeof-type-guards). One common approach is to create type guard functions like `isNumberNode` to filter specific nodes from a list:
```ts
import type { AppNode, NumberNode } from './types';
function isNumberNode(node: AppNode): node is NumberNode {
return node.type === 'number';
}
// numberNodes is now correctly typed as NumberNode[]
const numberNodes = computed(() => nodes.value.filter(isNumberNode));
```
Vue Flow also ships the `isNode` and `isEdge` type guards for narrowing an element to a node
or an edge.
### Uncontrolled Flow
Vue Flow runs in two modes. In a **controlled** flow you own the `nodes` and `edges` state and
apply every change yourself. In an **uncontrolled** (managed) flow Vue Flow keeps the state and
you read or change it through the instance. [Adding
Interactivity](/learn/concepts/adding-interactivity) covers the controlled path and the
`v-model` managed path in detail; this guide focuses on running a flow with no binding at all.
Unlike React Flow, Vue Flow has no `defaultNodes` / `defaultEdges` props. You seed the initial
graph through [`setupVueFlow()`](/api-reference/composables/setup-vue-flow) (or
[``](/api-reference/vue-flow-provider)) instead.
#### Seeding and driving through the instance
Pass the initial `nodes` and `edges` to `setupVueFlow()`, render `` with no `nodes` /
`edges` binding, and change the graph through the returned instance β here with `addNodes`:
```vue filename="App.vue"
```
Because you don't hold the nodes and edges in local state, you change them through instance
actions like [`addNodes`](/api-reference/composables/use-vue-flow), `updateNode`, and
`removeNodes` rather than reassigning an array.
Example: learn/uncontrolled
##### index.ts
```ts
import { createApp } from 'vue';
import App from './App.vue';
import './index.css';
createApp(App).mount('#app');
```
##### index.html
```html
Vue Flow Example
```
##### xy-extras.css
```css
/*
Extras for the xyflow examples. These styles sit on top of `@xyflow/vue/xy-theme.css`, which has to be
imported before this file. They only add what the library theme doesn't ship with.
*/
.vue-flow__panel {
color: var(--xy-theme-panel-text);
}
.vue-flow__node {
box-shadow: var(--xy-node-boxshadow-default);
}
.vue-flow__node-resizer {
border-radius: 0;
border: none;
}
/*
Custom Example CSS - This CSS is to improve the example experience.
You can remove it if you want to use the default styles.
New Theme Classes:
.xy-theme__button - Styles for buttons.
.xy-theme__input - Styles for text inputs.
.xy-theme__checkbox - Styles for checkboxes.
.xy-theme__select - Styles for dropdown selects.
.xy-theme__label - Styles for labels.
.xy-theme__range - Styles for range sliders (set --range-progress for the filled part).
Use these classes to apply consistent theming across your components.
*/
:root {
--color-primary: var(--xy-theme-primary);
--color-background: light-dark(#fefefe, #1a1b1e);
--color-hover-bg: light-dark(#f6f6f6, #24262c);
--color-disabled: light-dark(#76797e, #8b9099);
--color-primary-muted: color-mix(
in srgb,
var(--color-primary) 40%,
transparent
);
--color-primary-focus: color-mix(
in srgb,
var(--color-primary) 30%,
transparent
);
}
.xy-theme__button-group {
display: flex;
align-items: center;
.xy-theme__button:first-child {
border-radius: 100px 0 0 100px;
}
.xy-theme__button:last-child {
border-radius: 0 100px 100px 0;
margin: 0;
}
}
/* Custom Button Styling */
.xy-theme__button {
display: inline-flex;
align-items: center;
justify-content: center;
height: 2.5rem;
padding: 0 1rem;
border-radius: 100px;
border: 1px solid var(--color-primary);
background-color: var(--color-background);
color: var(--color-primary);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
box-shadow: var(--xy-node-boxshadow-default);
cursor: pointer;
}
.xy-theme__button.active {
background-color: var(--color-primary);
color: white;
border-color: var(--color-primary);
}
.xy-theme__button.active:hover,
.xy-theme__button.active:active {
background-color: var(--color-primary);
opacity: 0.9;
}
.xy-theme__button:hover {
background-color: var(--xy-controls-button-background-color-hover-default);
}
.xy-theme__button:active {
background-color: var(--color-hover-bg);
}
.xy-theme__button:disabled {
color: var(--color-disabled);
opacity: 0.8;
cursor: not-allowed;
border: 1px solid var(--color-disabled);
}
.xy-theme__button > span {
margin-right: 0.2rem;
}
/* Add gap between adjacent buttons */
.xy-theme__button + .xy-theme__button {
margin-left: 0.3rem;
}
/* Example Input Styling */
.xy-theme__input {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 7px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
}
.xy-theme__input:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Specific Checkbox Styling */
.xy-theme__checkbox {
appearance: none;
-webkit-appearance: none;
width: 1.25rem;
height: 1.25rem;
border-radius: 7px;
border: 2px solid var(--color-primary);
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
cursor: pointer;
display: inline-block;
vertical-align: middle;
margin-right: 0.5rem;
}
.xy-theme__checkbox:checked {
background-color: var(--color-primary);
border-color: var(--color-primary);
}
.xy-theme__checkbox:focus {
outline: none;
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Dropdown Styling */
.xy-theme__select {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 50px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
margin-right: 0.5rem;
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__select:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
.xy-theme__label {
margin-top: 10px;
margin-bottom: 3px;
display: inline-block;
color: var(--xy-theme-panel-text);
}
/* Range Slider Styling */
.xy-theme__input[type='range'],
.xy-theme__range {
-webkit-appearance: none;
appearance: none;
display: block;
width: 100%;
height: 0.5rem;
padding: 0;
border: none;
border-radius: 100px;
background: transparent;
cursor: pointer;
}
.xy-theme__input[type='range']:focus,
.xy-theme__range:focus {
outline: none;
box-shadow: none;
}
.xy-theme__input[type='range']::-webkit-slider-runnable-track,
.xy-theme__range::-webkit-slider-runnable-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: linear-gradient(
to right,
var(--color-primary-muted) 0%,
var(--color-primary-muted) var(--range-progress, 0%),
var(--color-hover-bg) var(--range-progress, 0%),
var(--color-hover-bg) 100%
);
}
.xy-theme__input[type='range']::-webkit-slider-thumb,
.xy-theme__range::-webkit-slider-thumb {
-webkit-appearance: none;
appearance: none;
width: 1.25rem;
height: 1.25rem;
margin-top: -0.375rem;
border-radius: 50%;
border: 2px solid var(--color-background);
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-track,
.xy-theme__range::-moz-range-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: var(--color-hover-bg);
}
.xy-theme__input[type='range']::-moz-range-thumb,
.xy-theme__range::-moz-range-thumb {
width: 1.25rem;
height: 1.25rem;
border: none;
border-radius: 50%;
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-progress,
.xy-theme__range::-moz-range-progress {
height: 0.5rem;
border-radius: 100px 0 0 100px;
background: var(--color-primary-muted);
}
```
##### index.css
```css
@import url('./xy-extras.css');
html,
body {
margin: 0;
font-family: sans-serif;
box-sizing: border-box;
}
#app {
width: 100vw;
height: 100vh;
}
```
##### App.vue
```vue
```
#### Connecting nodes
Vue Flow has no auto-connect, so new connections always come through the
[`@connect`](/learn/concepts/adding-interactivity#connecting-nodes) event. In an uncontrolled
flow, add the edge through the instance's `addEdges` instead of reassigning a local array:
```ts
const { addEdges } = setupVueFlow(/* ... */);
function onConnect(connection: Connection) {
addEdges([connection]);
}
```
`defaultEdgeOptions` is handy here: since you're not building each edge by hand, it's how you
give programmatically added edges a consistent look, such as making them `animated`.
### Whiteboard Features
Vue Flow is designed for building node-based UIs like workflow editors, flowcharts, and
diagrams. It isn't a whiteboard library, but you might still want common whiteboard features to
annotate or sketch alongside your nodes and edges. These examples show how to add drawing
capabilities to your application.
#### Examples
##### βοΈ Freehand draw (Pro)
Draw smooth curves on your Vue Flow pane, useful for annotations or sketching around existing
nodes.
**Features:**
* Mouse/touch drawing
* Adjustable brush size and color
* Converts drawn paths into custom nodes
**Common uses:**
* Annotating flowcharts
* Adding notes to diagrams
* Sketching ideas around nodes
Freehand draw is available as a [Vue Flow Pro](/pro) example.
##### π― Lasso selection
Select multiple elements by drawing a freeform selection area, with an option to include
partially selected elements.
**Features:**
* Freeform selection shapes
* Partial selection of elements
**Common uses:**
* Selecting nodes and annotations together
* Complex selections in mixed content
Example: examples/whiteboard/lasso-selection
##### utils.ts
```ts
import getStroke from 'perfect-freehand';
export const pathOptions = {
size: 7,
thinning: 0.5,
smoothing: 0.5,
streamline: 0.5,
easing: (t: number) => t,
start: {
taper: 0,
easing: (t: number) => t,
cap: true,
},
end: {
taper: 0.1,
easing: (t: number) => t,
cap: true,
},
};
export function getSvgPathFromStroke(stroke: number[][]) {
if (!stroke.length) {
return '';
}
const d = stroke.reduce(
(acc, [x0, y0], i, arr) => {
const [x1, y1] = arr[(i + 1) % arr.length];
acc.push(x0, y0, ',', (x0 + x1) / 2, (y0 + y1) / 2);
return acc;
},
['M', ...stroke[0], 'Q'] as (string | number)[],
);
d.push('Z');
return d.join(' ');
}
export function pointsToPath(points: [number, number, number][], zoom = 1) {
const stroke = getStroke(points, {
...pathOptions,
size: pathOptions.size * zoom,
});
return getSvgPathFromStroke(stroke);
}
```
##### xy-extras.css
```css
/*
Extras for the xyflow examples. These styles sit on top of `@xyflow/vue/xy-theme.css`, which has to be
imported before this file. They only add what the library theme doesn't ship with.
*/
.vue-flow__panel {
color: var(--xy-theme-panel-text);
}
.vue-flow__node {
box-shadow: var(--xy-node-boxshadow-default);
}
.vue-flow__node-resizer {
border-radius: 0;
border: none;
}
/*
Custom Example CSS - This CSS is to improve the example experience.
You can remove it if you want to use the default styles.
New Theme Classes:
.xy-theme__button - Styles for buttons.
.xy-theme__input - Styles for text inputs.
.xy-theme__checkbox - Styles for checkboxes.
.xy-theme__select - Styles for dropdown selects.
.xy-theme__label - Styles for labels.
.xy-theme__range - Styles for range sliders (set --range-progress for the filled part).
Use these classes to apply consistent theming across your components.
*/
:root {
--color-primary: var(--xy-theme-primary);
--color-background: light-dark(#fefefe, #1a1b1e);
--color-hover-bg: light-dark(#f6f6f6, #24262c);
--color-disabled: light-dark(#76797e, #8b9099);
--color-primary-muted: color-mix(
in srgb,
var(--color-primary) 40%,
transparent
);
--color-primary-focus: color-mix(
in srgb,
var(--color-primary) 30%,
transparent
);
}
.xy-theme__button-group {
display: flex;
align-items: center;
.xy-theme__button:first-child {
border-radius: 100px 0 0 100px;
}
.xy-theme__button:last-child {
border-radius: 0 100px 100px 0;
margin: 0;
}
}
/* Custom Button Styling */
.xy-theme__button {
display: inline-flex;
align-items: center;
justify-content: center;
height: 2.5rem;
padding: 0 1rem;
border-radius: 100px;
border: 1px solid var(--color-primary);
background-color: var(--color-background);
color: var(--color-primary);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
box-shadow: var(--xy-node-boxshadow-default);
cursor: pointer;
}
.xy-theme__button.active {
background-color: var(--color-primary);
color: white;
border-color: var(--color-primary);
}
.xy-theme__button.active:hover,
.xy-theme__button.active:active {
background-color: var(--color-primary);
opacity: 0.9;
}
.xy-theme__button:hover {
background-color: var(--xy-controls-button-background-color-hover-default);
}
.xy-theme__button:active {
background-color: var(--color-hover-bg);
}
.xy-theme__button:disabled {
color: var(--color-disabled);
opacity: 0.8;
cursor: not-allowed;
border: 1px solid var(--color-disabled);
}
.xy-theme__button > span {
margin-right: 0.2rem;
}
/* Add gap between adjacent buttons */
.xy-theme__button + .xy-theme__button {
margin-left: 0.3rem;
}
/* Example Input Styling */
.xy-theme__input {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 7px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
}
.xy-theme__input:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Specific Checkbox Styling */
.xy-theme__checkbox {
appearance: none;
-webkit-appearance: none;
width: 1.25rem;
height: 1.25rem;
border-radius: 7px;
border: 2px solid var(--color-primary);
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
cursor: pointer;
display: inline-block;
vertical-align: middle;
margin-right: 0.5rem;
}
.xy-theme__checkbox:checked {
background-color: var(--color-primary);
border-color: var(--color-primary);
}
.xy-theme__checkbox:focus {
outline: none;
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Dropdown Styling */
.xy-theme__select {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 50px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
margin-right: 0.5rem;
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__select:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
.xy-theme__label {
margin-top: 10px;
margin-bottom: 3px;
display: inline-block;
color: var(--xy-theme-panel-text);
}
/* Range Slider Styling */
.xy-theme__input[type='range'],
.xy-theme__range {
-webkit-appearance: none;
appearance: none;
display: block;
width: 100%;
height: 0.5rem;
padding: 0;
border: none;
border-radius: 100px;
background: transparent;
cursor: pointer;
}
.xy-theme__input[type='range']:focus,
.xy-theme__range:focus {
outline: none;
box-shadow: none;
}
.xy-theme__input[type='range']::-webkit-slider-runnable-track,
.xy-theme__range::-webkit-slider-runnable-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: linear-gradient(
to right,
var(--color-primary-muted) 0%,
var(--color-primary-muted) var(--range-progress, 0%),
var(--color-hover-bg) var(--range-progress, 0%),
var(--color-hover-bg) 100%
);
}
.xy-theme__input[type='range']::-webkit-slider-thumb,
.xy-theme__range::-webkit-slider-thumb {
-webkit-appearance: none;
appearance: none;
width: 1.25rem;
height: 1.25rem;
margin-top: -0.375rem;
border-radius: 50%;
border: 2px solid var(--color-background);
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-track,
.xy-theme__range::-moz-range-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: var(--color-hover-bg);
}
.xy-theme__input[type='range']::-moz-range-thumb,
.xy-theme__range::-moz-range-thumb {
width: 1.25rem;
height: 1.25rem;
border: none;
border-radius: 50%;
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-progress,
.xy-theme__range::-moz-range-progress {
height: 0.5rem;
border-radius: 100px 0 0 100px;
background: var(--color-primary-muted);
}
```
##### index.css
```css
@import url('@xyflow/vue/xy-theme.css');
@import url('./xy-extras.css');
html,
body {
margin: 0;
font-family: sans-serif;
box-sizing: border-box;
}
#app {
width: 100vw;
height: 100vh;
}
.tool-overlay {
pointer-events: auto;
position: absolute;
top: 0;
left: 0;
z-index: 4;
height: 100%;
width: 100%;
transform-origin: top left;
touch-action: none;
}
.lasso-controls {
display: flex;
align-items: center;
gap: 10px;
}
.lasso-controls button {
width: 150px;
}
.lasso-controls label {
display: flex;
align-items: center;
justify-content: center;
line-height: 1;
color: light-dark(#111827, #f3f4f6);
}
```
##### Lasso.vue
```vue
```
##### App.vue
```vue
```
##### π§Ή Eraser
Remove items by "erasing" over them. Uses collision detection to determine what to delete.
**Features:**
* Collision-based erasing
* Visual eraser cursor
**Common uses:**
* Removing parts of a flow
Example: examples/whiteboard/eraser
##### utils.ts
```ts
// Utility functions for geometric intersection detection
type Point = [number, number];
type Rectangle = { x: number; y: number; width: number; height: number };
// Check if two line segments intersect
function lineSegmentsIntersect(
p1: Point,
p2: Point,
p3: Point,
p4: Point,
): boolean {
const [x1, y1] = p1;
const [x2, y2] = p2;
const [x3, y3] = p3;
const [x4, y4] = p4;
const denom = (x1 - x2) * (y3 - y4) - (y1 - y2) * (x3 - x4);
if (Math.abs(denom) < 1e-10) {
return false; // Lines are parallel
}
const t = ((x1 - x3) * (y3 - y4) - (y1 - y3) * (x3 - x4)) / denom;
const u = -((x1 - x2) * (y1 - y3) - (y1 - y2) * (x1 - x3)) / denom;
return t >= 0 && t <= 1 && u >= 0 && u <= 1;
}
// Check if a point is inside a rectangle
function pointInRectangle(point: Point, rect: Rectangle): boolean {
const [x, y] = point;
return (
x >= rect.x &&
x <= rect.x + rect.width &&
y >= rect.y &&
y <= rect.y + rect.height
);
}
// Get the four edges of a rectangle as line segments
function getRectangleEdges(rect: Rectangle): [Point, Point][] {
const { x, y, width, height } = rect;
return [
[
[x, y],
[x + width, y],
], // top edge
[
[x + width, y],
[x + width, y + height],
], // right edge
[
[x + width, y + height],
[x, y + height],
], // bottom edge
[
[x, y + height],
[x, y],
], // left edge
];
}
// Check if a polyline (series of connected line segments) intersects with a rectangle
export function polylineIntersectsRectangle(
points: Point[],
rect: Rectangle,
): boolean {
if (points.length < 2) {
return false;
}
// Early return if any point is inside the rectangle
for (const point of points) {
if (pointInRectangle(point, rect)) {
return true;
}
}
// Check if any line segment intersects with rectangle edges
const rectEdges = getRectangleEdges(rect);
for (let i = 0; i < points.length - 1; i++) {
const lineStart = points[i];
const lineEnd = points[i + 1];
for (const [edgeStart, edgeEnd] of rectEdges) {
if (lineSegmentsIntersect(lineStart, lineEnd, edgeStart, edgeEnd)) {
return true;
}
}
}
return false;
}
// Calculate distance between two points
function distanceBetweenPoints(p1: Point, p2: Point): number {
const [x1, y1] = p1;
const [x2, y2] = p2;
return Math.sqrt((x2 - x1) ** 2 + (y2 - y1) ** 2);
}
// Calculate the closest point on a line segment to a given point
function closestPointOnSegment(
point: Point,
segmentStart: Point,
segmentEnd: Point,
): Point {
const [px, py] = point;
const [x1, y1] = segmentStart;
const [x2, y2] = segmentEnd;
const dx = x2 - x1;
const dy = y2 - y1;
const lengthSquared = dx * dx + dy * dy;
if (lengthSquared === 0) {
return segmentStart; // Segment is a point
}
const t = Math.max(
0,
Math.min(1, ((px - x1) * dx + (py - y1) * dy) / lengthSquared),
);
return [x1 + t * dx, y1 + t * dy];
}
// Check if two paths intersect using a more efficient approach
export function pathsIntersect(
path1: Point[],
path2: Point[],
threshold = 1,
): boolean {
if (path1.length < 2 || path2.length < 2) {
return false;
}
// First, do the more precise line segment intersection check
for (let i = 0; i < path1.length - 1; i++) {
for (let j = 0; j < path2.length - 1; j++) {
if (
lineSegmentsIntersect(path1[i], path1[i + 1], path2[j], path2[j + 1])
) {
return true;
}
}
}
// If no exact intersection, check for proximity based on threshold
if (threshold > 0) {
for (let i = 0; i < path1.length - 1; i++) {
const segment1Start = path1[i];
const segment1End = path1[i + 1];
for (let j = 0; j < path2.length - 1; j++) {
const segment2Start = path2[j];
const segment2End = path2[j + 1];
// Check distance between segment endpoints and closest points
const distances = [
distanceBetweenPoints(
segment1Start,
closestPointOnSegment(segment1Start, segment2Start, segment2End),
),
distanceBetweenPoints(
segment1End,
closestPointOnSegment(segment1End, segment2Start, segment2End),
),
distanceBetweenPoints(
segment2Start,
closestPointOnSegment(segment2Start, segment1Start, segment1End),
),
distanceBetweenPoints(
segment2End,
closestPointOnSegment(segment2End, segment1Start, segment1End),
),
];
if (Math.min(...distances) <= threshold) {
return true;
}
}
}
}
return false;
}
```
##### types.ts
```ts
import type { Edge, Node } from '@xyflow/vue';
export type ErasableNodeType = Node<
{ toBeDeleted?: boolean; label?: string },
'erasable-node'
>;
export type ErasableEdgeType = Edge<{ toBeDeleted?: boolean }, 'erasable-edge'>;
```
##### xy-extras.css
```css
/*
Extras for the xyflow examples. These styles sit on top of `@xyflow/vue/xy-theme.css`, which has to be
imported before this file. They only add what the library theme doesn't ship with.
*/
.vue-flow__panel {
color: var(--xy-theme-panel-text);
}
.vue-flow__node {
box-shadow: var(--xy-node-boxshadow-default);
}
.vue-flow__node-resizer {
border-radius: 0;
border: none;
}
/*
Custom Example CSS - This CSS is to improve the example experience.
You can remove it if you want to use the default styles.
New Theme Classes:
.xy-theme__button - Styles for buttons.
.xy-theme__input - Styles for text inputs.
.xy-theme__checkbox - Styles for checkboxes.
.xy-theme__select - Styles for dropdown selects.
.xy-theme__label - Styles for labels.
.xy-theme__range - Styles for range sliders (set --range-progress for the filled part).
Use these classes to apply consistent theming across your components.
*/
:root {
--color-primary: var(--xy-theme-primary);
--color-background: light-dark(#fefefe, #1a1b1e);
--color-hover-bg: light-dark(#f6f6f6, #24262c);
--color-disabled: light-dark(#76797e, #8b9099);
--color-primary-muted: color-mix(
in srgb,
var(--color-primary) 40%,
transparent
);
--color-primary-focus: color-mix(
in srgb,
var(--color-primary) 30%,
transparent
);
}
.xy-theme__button-group {
display: flex;
align-items: center;
.xy-theme__button:first-child {
border-radius: 100px 0 0 100px;
}
.xy-theme__button:last-child {
border-radius: 0 100px 100px 0;
margin: 0;
}
}
/* Custom Button Styling */
.xy-theme__button {
display: inline-flex;
align-items: center;
justify-content: center;
height: 2.5rem;
padding: 0 1rem;
border-radius: 100px;
border: 1px solid var(--color-primary);
background-color: var(--color-background);
color: var(--color-primary);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
box-shadow: var(--xy-node-boxshadow-default);
cursor: pointer;
}
.xy-theme__button.active {
background-color: var(--color-primary);
color: white;
border-color: var(--color-primary);
}
.xy-theme__button.active:hover,
.xy-theme__button.active:active {
background-color: var(--color-primary);
opacity: 0.9;
}
.xy-theme__button:hover {
background-color: var(--xy-controls-button-background-color-hover-default);
}
.xy-theme__button:active {
background-color: var(--color-hover-bg);
}
.xy-theme__button:disabled {
color: var(--color-disabled);
opacity: 0.8;
cursor: not-allowed;
border: 1px solid var(--color-disabled);
}
.xy-theme__button > span {
margin-right: 0.2rem;
}
/* Add gap between adjacent buttons */
.xy-theme__button + .xy-theme__button {
margin-left: 0.3rem;
}
/* Example Input Styling */
.xy-theme__input {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 7px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
}
.xy-theme__input:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Specific Checkbox Styling */
.xy-theme__checkbox {
appearance: none;
-webkit-appearance: none;
width: 1.25rem;
height: 1.25rem;
border-radius: 7px;
border: 2px solid var(--color-primary);
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
cursor: pointer;
display: inline-block;
vertical-align: middle;
margin-right: 0.5rem;
}
.xy-theme__checkbox:checked {
background-color: var(--color-primary);
border-color: var(--color-primary);
}
.xy-theme__checkbox:focus {
outline: none;
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Dropdown Styling */
.xy-theme__select {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 50px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
margin-right: 0.5rem;
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__select:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
.xy-theme__label {
margin-top: 10px;
margin-bottom: 3px;
display: inline-block;
color: var(--xy-theme-panel-text);
}
/* Range Slider Styling */
.xy-theme__input[type='range'],
.xy-theme__range {
-webkit-appearance: none;
appearance: none;
display: block;
width: 100%;
height: 0.5rem;
padding: 0;
border: none;
border-radius: 100px;
background: transparent;
cursor: pointer;
}
.xy-theme__input[type='range']:focus,
.xy-theme__range:focus {
outline: none;
box-shadow: none;
}
.xy-theme__input[type='range']::-webkit-slider-runnable-track,
.xy-theme__range::-webkit-slider-runnable-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: linear-gradient(
to right,
var(--color-primary-muted) 0%,
var(--color-primary-muted) var(--range-progress, 0%),
var(--color-hover-bg) var(--range-progress, 0%),
var(--color-hover-bg) 100%
);
}
.xy-theme__input[type='range']::-webkit-slider-thumb,
.xy-theme__range::-webkit-slider-thumb {
-webkit-appearance: none;
appearance: none;
width: 1.25rem;
height: 1.25rem;
margin-top: -0.375rem;
border-radius: 50%;
border: 2px solid var(--color-background);
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-track,
.xy-theme__range::-moz-range-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: var(--color-hover-bg);
}
.xy-theme__input[type='range']::-moz-range-thumb,
.xy-theme__range::-moz-range-thumb {
width: 1.25rem;
height: 1.25rem;
border: none;
border-radius: 50%;
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-progress,
.xy-theme__range::-moz-range-progress {
height: 0.5rem;
border-radius: 100px 0 0 100px;
background: var(--color-primary-muted);
}
```
##### index.css
```css
@import url('@xyflow/vue/xy-theme.css');
@import url('./xy-extras.css');
html,
body {
margin: 0;
font-family: sans-serif;
box-sizing: border-box;
}
#app {
width: 100vw;
height: 100vh;
}
.tool-overlay {
pointer-events: auto;
position: absolute;
top: 0;
left: 0;
z-index: 4;
height: 100%;
width: 100%;
transform-origin: top left;
cursor: crosshair;
touch-action: none;
}
```
##### Eraser.vue
```vue
```
##### ErasableNode.vue
```vue
```
#### Whiteboard libraries
If you're looking for a more complete whiteboard solution, consider libraries designed
specifically for it, like [tldraw](https://tldraw.dev/) or
[Excalidraw](https://docs.excalidraw.com/). These provide a full set of features for
collaborative drawing, shapes, text, and more.
### Adding Interactivity
In the [previous guide](/learn/concepts/building-a-flow) we built a flow with a couple
of nodes and an edge. Because we bound our nodes and edges with `v-model`, that flow is
*already* interactive: you can select, drag, and delete nodes and edges out of the box.
This is the biggest difference from React Flow and Svelte Flow. When you use
`v-model:nodes` / `v-model:edges`, Vue Flow **manages the state for you**: it applies
changes, like a node being dragged or an element being deleted, directly
to your arrays. We call this an **uncontrolled** flow.
#### Uncontrolled flow with v-model
Binding `nodes` and `edges` with `v-model` is all you need for a flow where users can
move, select, and remove elements:
```vue "v-model:nodes" "v-model:edges"
```
Vue Flow replaces the whole `nodes` / `edges` array when it applies a change, so a
[`shallowRef`](https://vuejs.org/api/reactivity-advanced.html#shallowref) is enough,
and much cheaper than a deep `ref` for large flows.
#### Connecting nodes
One thing is *not* applied automatically: creating a new edge when the user drags from
one node's handle to another. For that, listen to the `@connect` event and append the new
edge with the [`addEdge`](/api-reference/utils/add-edge) utility.
##### Import `addEdge`
```ts
import { addEdge } from '@xyflow/vue';
```
##### Add a connect handler
`addEdge` takes the new [`Connection`](/api-reference/types/connection) and the current
edges array, and returns a new array with the edge appended:
```ts
function onConnect(connection: Connection) {
edges.value = addEdge(connection, edges.value);
}
```
##### Pass it to VueFlow
```vue "@connect"
```
##### Connectable flow
Try dragging from one node's handle to the other. The `@connect` handler fires and the new
edge is added. π₯³
Example: learn/make-it-interactive-1
##### index.ts
```ts
import { createApp } from 'vue';
import App from './App.vue';
import './index.css';
createApp(App).mount('#app');
```
##### index.html
```html
Vue Flow Example
```
##### xy-extras.css
```css
/*
Extras for the xyflow examples. These styles sit on top of `@xyflow/vue/xy-theme.css`, which has to be
imported before this file. They only add what the library theme doesn't ship with.
*/
.vue-flow__panel {
color: var(--xy-theme-panel-text);
}
.vue-flow__node {
box-shadow: var(--xy-node-boxshadow-default);
}
.vue-flow__node-resizer {
border-radius: 0;
border: none;
}
/*
Custom Example CSS - This CSS is to improve the example experience.
You can remove it if you want to use the default styles.
New Theme Classes:
.xy-theme__button - Styles for buttons.
.xy-theme__input - Styles for text inputs.
.xy-theme__checkbox - Styles for checkboxes.
.xy-theme__select - Styles for dropdown selects.
.xy-theme__label - Styles for labels.
.xy-theme__range - Styles for range sliders (set --range-progress for the filled part).
Use these classes to apply consistent theming across your components.
*/
:root {
--color-primary: var(--xy-theme-primary);
--color-background: light-dark(#fefefe, #1a1b1e);
--color-hover-bg: light-dark(#f6f6f6, #24262c);
--color-disabled: light-dark(#76797e, #8b9099);
--color-primary-muted: color-mix(
in srgb,
var(--color-primary) 40%,
transparent
);
--color-primary-focus: color-mix(
in srgb,
var(--color-primary) 30%,
transparent
);
}
.xy-theme__button-group {
display: flex;
align-items: center;
.xy-theme__button:first-child {
border-radius: 100px 0 0 100px;
}
.xy-theme__button:last-child {
border-radius: 0 100px 100px 0;
margin: 0;
}
}
/* Custom Button Styling */
.xy-theme__button {
display: inline-flex;
align-items: center;
justify-content: center;
height: 2.5rem;
padding: 0 1rem;
border-radius: 100px;
border: 1px solid var(--color-primary);
background-color: var(--color-background);
color: var(--color-primary);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
box-shadow: var(--xy-node-boxshadow-default);
cursor: pointer;
}
.xy-theme__button.active {
background-color: var(--color-primary);
color: white;
border-color: var(--color-primary);
}
.xy-theme__button.active:hover,
.xy-theme__button.active:active {
background-color: var(--color-primary);
opacity: 0.9;
}
.xy-theme__button:hover {
background-color: var(--xy-controls-button-background-color-hover-default);
}
.xy-theme__button:active {
background-color: var(--color-hover-bg);
}
.xy-theme__button:disabled {
color: var(--color-disabled);
opacity: 0.8;
cursor: not-allowed;
border: 1px solid var(--color-disabled);
}
.xy-theme__button > span {
margin-right: 0.2rem;
}
/* Add gap between adjacent buttons */
.xy-theme__button + .xy-theme__button {
margin-left: 0.3rem;
}
/* Example Input Styling */
.xy-theme__input {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 7px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
}
.xy-theme__input:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Specific Checkbox Styling */
.xy-theme__checkbox {
appearance: none;
-webkit-appearance: none;
width: 1.25rem;
height: 1.25rem;
border-radius: 7px;
border: 2px solid var(--color-primary);
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
cursor: pointer;
display: inline-block;
vertical-align: middle;
margin-right: 0.5rem;
}
.xy-theme__checkbox:checked {
background-color: var(--color-primary);
border-color: var(--color-primary);
}
.xy-theme__checkbox:focus {
outline: none;
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Dropdown Styling */
.xy-theme__select {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 50px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
margin-right: 0.5rem;
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__select:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
.xy-theme__label {
margin-top: 10px;
margin-bottom: 3px;
display: inline-block;
color: var(--xy-theme-panel-text);
}
/* Range Slider Styling */
.xy-theme__input[type='range'],
.xy-theme__range {
-webkit-appearance: none;
appearance: none;
display: block;
width: 100%;
height: 0.5rem;
padding: 0;
border: none;
border-radius: 100px;
background: transparent;
cursor: pointer;
}
.xy-theme__input[type='range']:focus,
.xy-theme__range:focus {
outline: none;
box-shadow: none;
}
.xy-theme__input[type='range']::-webkit-slider-runnable-track,
.xy-theme__range::-webkit-slider-runnable-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: linear-gradient(
to right,
var(--color-primary-muted) 0%,
var(--color-primary-muted) var(--range-progress, 0%),
var(--color-hover-bg) var(--range-progress, 0%),
var(--color-hover-bg) 100%
);
}
.xy-theme__input[type='range']::-webkit-slider-thumb,
.xy-theme__range::-webkit-slider-thumb {
-webkit-appearance: none;
appearance: none;
width: 1.25rem;
height: 1.25rem;
margin-top: -0.375rem;
border-radius: 50%;
border: 2px solid var(--color-background);
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-track,
.xy-theme__range::-moz-range-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: var(--color-hover-bg);
}
.xy-theme__input[type='range']::-moz-range-thumb,
.xy-theme__range::-moz-range-thumb {
width: 1.25rem;
height: 1.25rem;
border: none;
border-radius: 50%;
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-progress,
.xy-theme__range::-moz-range-progress {
height: 0.5rem;
border-radius: 100px 0 0 100px;
background: var(--color-primary-muted);
}
```
##### index.css
```css
@import url('./xy-extras.css');
html,
body {
margin: 0;
font-family: sans-serif;
box-sizing: border-box;
}
#app {
width: 100vw;
height: 100vh;
}
```
##### App.vue
```vue
```
#### Controlled flow
Sometimes you want full control over the state so you can validate, transform, or persist every
change yourself rather than letting Vue Flow apply it. To do that, drop `v-model` and pass
`nodes` and `edges` as one-way props, then handle the `@nodes-change` and `@edges-change`
events yourself β each one hands you a changeset that knows how to apply itself.
For most apps `v-model` is the simpler choice. Reach for a controlled flow only when you
need to inspect or intercept every change before it is applied.
##### Handle the change events
Each handler receives a changeset of [changes](/api-reference/types/node-change). Call
`applyTo` with your current array and it returns the next one:
```ts
import type { Edge, EdgeChangeset, Node, NodeChangeset } from '@xyflow/vue';
import { addEdge } from '@xyflow/vue';
function onNodesChange(changes: NodeChangeset) {
nodes.value = changes.applyTo(nodes.value);
}
function onEdgesChange(changes: EdgeChangeset) {
edges.value = changes.applyTo(edges.value);
}
function onConnect(connection: Connection) {
edges.value = addEdge(connection, edges.value);
}
```
##### Pass them to VueFlow
```vue "@nodes-change" "@edges-change" "@connect"
```
##### Controlled flow
The result looks identical, but now every change passes through your handlers before it
touches the arrays.
Example: learn/make-it-interactive-2
##### index.ts
```ts
import { createApp } from 'vue';
import App from './App.vue';
import './index.css';
createApp(App).mount('#app');
```
##### index.html
```html
Vue Flow Example
```
##### xy-extras.css
```css
/*
Extras for the xyflow examples. These styles sit on top of `@xyflow/vue/xy-theme.css`, which has to be
imported before this file. They only add what the library theme doesn't ship with.
*/
.vue-flow__panel {
color: var(--xy-theme-panel-text);
}
.vue-flow__node {
box-shadow: var(--xy-node-boxshadow-default);
}
.vue-flow__node-resizer {
border-radius: 0;
border: none;
}
/*
Custom Example CSS - This CSS is to improve the example experience.
You can remove it if you want to use the default styles.
New Theme Classes:
.xy-theme__button - Styles for buttons.
.xy-theme__input - Styles for text inputs.
.xy-theme__checkbox - Styles for checkboxes.
.xy-theme__select - Styles for dropdown selects.
.xy-theme__label - Styles for labels.
.xy-theme__range - Styles for range sliders (set --range-progress for the filled part).
Use these classes to apply consistent theming across your components.
*/
:root {
--color-primary: var(--xy-theme-primary);
--color-background: light-dark(#fefefe, #1a1b1e);
--color-hover-bg: light-dark(#f6f6f6, #24262c);
--color-disabled: light-dark(#76797e, #8b9099);
--color-primary-muted: color-mix(
in srgb,
var(--color-primary) 40%,
transparent
);
--color-primary-focus: color-mix(
in srgb,
var(--color-primary) 30%,
transparent
);
}
.xy-theme__button-group {
display: flex;
align-items: center;
.xy-theme__button:first-child {
border-radius: 100px 0 0 100px;
}
.xy-theme__button:last-child {
border-radius: 0 100px 100px 0;
margin: 0;
}
}
/* Custom Button Styling */
.xy-theme__button {
display: inline-flex;
align-items: center;
justify-content: center;
height: 2.5rem;
padding: 0 1rem;
border-radius: 100px;
border: 1px solid var(--color-primary);
background-color: var(--color-background);
color: var(--color-primary);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
box-shadow: var(--xy-node-boxshadow-default);
cursor: pointer;
}
.xy-theme__button.active {
background-color: var(--color-primary);
color: white;
border-color: var(--color-primary);
}
.xy-theme__button.active:hover,
.xy-theme__button.active:active {
background-color: var(--color-primary);
opacity: 0.9;
}
.xy-theme__button:hover {
background-color: var(--xy-controls-button-background-color-hover-default);
}
.xy-theme__button:active {
background-color: var(--color-hover-bg);
}
.xy-theme__button:disabled {
color: var(--color-disabled);
opacity: 0.8;
cursor: not-allowed;
border: 1px solid var(--color-disabled);
}
.xy-theme__button > span {
margin-right: 0.2rem;
}
/* Add gap between adjacent buttons */
.xy-theme__button + .xy-theme__button {
margin-left: 0.3rem;
}
/* Example Input Styling */
.xy-theme__input {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 7px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
}
.xy-theme__input:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Specific Checkbox Styling */
.xy-theme__checkbox {
appearance: none;
-webkit-appearance: none;
width: 1.25rem;
height: 1.25rem;
border-radius: 7px;
border: 2px solid var(--color-primary);
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
cursor: pointer;
display: inline-block;
vertical-align: middle;
margin-right: 0.5rem;
}
.xy-theme__checkbox:checked {
background-color: var(--color-primary);
border-color: var(--color-primary);
}
.xy-theme__checkbox:focus {
outline: none;
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Dropdown Styling */
.xy-theme__select {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 50px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
margin-right: 0.5rem;
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__select:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
.xy-theme__label {
margin-top: 10px;
margin-bottom: 3px;
display: inline-block;
color: var(--xy-theme-panel-text);
}
/* Range Slider Styling */
.xy-theme__input[type='range'],
.xy-theme__range {
-webkit-appearance: none;
appearance: none;
display: block;
width: 100%;
height: 0.5rem;
padding: 0;
border: none;
border-radius: 100px;
background: transparent;
cursor: pointer;
}
.xy-theme__input[type='range']:focus,
.xy-theme__range:focus {
outline: none;
box-shadow: none;
}
.xy-theme__input[type='range']::-webkit-slider-runnable-track,
.xy-theme__range::-webkit-slider-runnable-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: linear-gradient(
to right,
var(--color-primary-muted) 0%,
var(--color-primary-muted) var(--range-progress, 0%),
var(--color-hover-bg) var(--range-progress, 0%),
var(--color-hover-bg) 100%
);
}
.xy-theme__input[type='range']::-webkit-slider-thumb,
.xy-theme__range::-webkit-slider-thumb {
-webkit-appearance: none;
appearance: none;
width: 1.25rem;
height: 1.25rem;
margin-top: -0.375rem;
border-radius: 50%;
border: 2px solid var(--color-background);
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-track,
.xy-theme__range::-moz-range-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: var(--color-hover-bg);
}
.xy-theme__input[type='range']::-moz-range-thumb,
.xy-theme__range::-moz-range-thumb {
width: 1.25rem;
height: 1.25rem;
border: none;
border-radius: 50%;
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-progress,
.xy-theme__range::-moz-range-progress {
height: 0.5rem;
border-radius: 100px 0 0 100px;
background: var(--color-primary-muted);
}
```
##### index.css
```css
@import url('./xy-extras.css');
html,
body {
margin: 0;
font-family: sans-serif;
box-sizing: border-box;
}
#app {
width: 100vw;
height: 100vh;
}
```
##### App.vue
```vue
```
#### What you get
Whichever approach you choose, an interactive flow lets your users:
* select nodes and edges
* drag nodes around the canvas
* connect nodes by dragging from one handle to another
* draw a multi-selection box by holding `Shift` β the default
[`selectionKeyCode`](/api-reference/vue-flow)
* add to a selection by holding `Meta`/`Control` β the default
[`multiSelectionKeyCode`](/api-reference/vue-flow)
* remove selected elements with `Backspace` β the default
[`deleteKeyCode`](/api-reference/vue-flow)
If you want to jump straight into building your own application, we recommend checking out
the [Customization](/learn/customization/custom-nodes) section.
### Building a Flow
In the following pages we will introduce you to the core concepts of Vue Flow and explain how to create a basic interactive flow.
A flow consists of [nodes](/api-reference/types/node) and [edges](/api-reference/types/edge)
placed inside a pannable and zoomable viewport. If you haven't already, we recommend
having a look at the [core concepts overview](/learn/concepts/terms-and-definitions)
first.
To follow along with this guide you will need to have a Vue project set up and install
the `@xyflow/vue` package:
```bash copy npm2yarn
npm install @xyflow/vue
```
#### Creating the flow
Let's start by creating an empty flow with [``](/api-reference/components/controls)
for the viewport and a dotted [``](/api-reference/components/background).
##### Add imports
All the imports we need are importable from `@xyflow/vue`, so let's import the
main `` component and the background and controls components mentioned
above.
```vue
```
It's also important to import the default styles for Vue Flow. You can't skip this
step because the styles are required for the flow to render *and* function correctly.
```vue
```
##### Render VueFlow
Next, render the main component inside an element with defined dimensions and place
the [``](/api-reference/components/background) and
[``](/api-reference/components/controls) components inside ``
Content inside `` is fixed _on top_ of the viewport. The ``
component transforms its pattern to match viewport movement.
```vue
```
##### Empty flow
That's it! You have created your first empty flow π
If everything is set up correctly, you should see a blank canvas like this:
Example: learn/building-a-flow-1
##### index.ts
```ts
import { createApp } from 'vue';
import App from './App.vue';
import './index.css';
createApp(App).mount('#app');
```
##### index.html
```html
Vue Flow Example
```
##### xy-extras.css
```css
/*
Extras for the xyflow examples. These styles sit on top of `@xyflow/vue/xy-theme.css`, which has to be
imported before this file. They only add what the library theme doesn't ship with.
*/
.vue-flow__panel {
color: var(--xy-theme-panel-text);
}
.vue-flow__node {
box-shadow: var(--xy-node-boxshadow-default);
}
.vue-flow__node-resizer {
border-radius: 0;
border: none;
}
/*
Custom Example CSS - This CSS is to improve the example experience.
You can remove it if you want to use the default styles.
New Theme Classes:
.xy-theme__button - Styles for buttons.
.xy-theme__input - Styles for text inputs.
.xy-theme__checkbox - Styles for checkboxes.
.xy-theme__select - Styles for dropdown selects.
.xy-theme__label - Styles for labels.
.xy-theme__range - Styles for range sliders (set --range-progress for the filled part).
Use these classes to apply consistent theming across your components.
*/
:root {
--color-primary: var(--xy-theme-primary);
--color-background: light-dark(#fefefe, #1a1b1e);
--color-hover-bg: light-dark(#f6f6f6, #24262c);
--color-disabled: light-dark(#76797e, #8b9099);
--color-primary-muted: color-mix(
in srgb,
var(--color-primary) 40%,
transparent
);
--color-primary-focus: color-mix(
in srgb,
var(--color-primary) 30%,
transparent
);
}
.xy-theme__button-group {
display: flex;
align-items: center;
.xy-theme__button:first-child {
border-radius: 100px 0 0 100px;
}
.xy-theme__button:last-child {
border-radius: 0 100px 100px 0;
margin: 0;
}
}
/* Custom Button Styling */
.xy-theme__button {
display: inline-flex;
align-items: center;
justify-content: center;
height: 2.5rem;
padding: 0 1rem;
border-radius: 100px;
border: 1px solid var(--color-primary);
background-color: var(--color-background);
color: var(--color-primary);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
box-shadow: var(--xy-node-boxshadow-default);
cursor: pointer;
}
.xy-theme__button.active {
background-color: var(--color-primary);
color: white;
border-color: var(--color-primary);
}
.xy-theme__button.active:hover,
.xy-theme__button.active:active {
background-color: var(--color-primary);
opacity: 0.9;
}
.xy-theme__button:hover {
background-color: var(--xy-controls-button-background-color-hover-default);
}
.xy-theme__button:active {
background-color: var(--color-hover-bg);
}
.xy-theme__button:disabled {
color: var(--color-disabled);
opacity: 0.8;
cursor: not-allowed;
border: 1px solid var(--color-disabled);
}
.xy-theme__button > span {
margin-right: 0.2rem;
}
/* Add gap between adjacent buttons */
.xy-theme__button + .xy-theme__button {
margin-left: 0.3rem;
}
/* Example Input Styling */
.xy-theme__input {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 7px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
}
.xy-theme__input:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Specific Checkbox Styling */
.xy-theme__checkbox {
appearance: none;
-webkit-appearance: none;
width: 1.25rem;
height: 1.25rem;
border-radius: 7px;
border: 2px solid var(--color-primary);
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
cursor: pointer;
display: inline-block;
vertical-align: middle;
margin-right: 0.5rem;
}
.xy-theme__checkbox:checked {
background-color: var(--color-primary);
border-color: var(--color-primary);
}
.xy-theme__checkbox:focus {
outline: none;
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
/* Dropdown Styling */
.xy-theme__select {
padding: 0.5rem 0.75rem;
border: 1px solid var(--color-primary);
border-radius: 50px;
background-color: var(--color-background);
transition:
background-color 0.2s ease,
border-color 0.2s ease;
font-size: 1rem;
color: var(--xy-theme-panel-text);
margin-right: 0.5rem;
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__select:focus {
outline: none;
border-color: var(--color-primary);
box-shadow: 0 0 0 2px var(--color-primary-focus);
}
.xy-theme__label {
margin-top: 10px;
margin-bottom: 3px;
display: inline-block;
color: var(--xy-theme-panel-text);
}
/* Range Slider Styling */
.xy-theme__input[type='range'],
.xy-theme__range {
-webkit-appearance: none;
appearance: none;
display: block;
width: 100%;
height: 0.5rem;
padding: 0;
border: none;
border-radius: 100px;
background: transparent;
cursor: pointer;
}
.xy-theme__input[type='range']:focus,
.xy-theme__range:focus {
outline: none;
box-shadow: none;
}
.xy-theme__input[type='range']::-webkit-slider-runnable-track,
.xy-theme__range::-webkit-slider-runnable-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: linear-gradient(
to right,
var(--color-primary-muted) 0%,
var(--color-primary-muted) var(--range-progress, 0%),
var(--color-hover-bg) var(--range-progress, 0%),
var(--color-hover-bg) 100%
);
}
.xy-theme__input[type='range']::-webkit-slider-thumb,
.xy-theme__range::-webkit-slider-thumb {
-webkit-appearance: none;
appearance: none;
width: 1.25rem;
height: 1.25rem;
margin-top: -0.375rem;
border-radius: 50%;
border: 2px solid var(--color-background);
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-track,
.xy-theme__range::-moz-range-track {
width: 100%;
height: 0.5rem;
border-radius: 100px;
background: var(--color-hover-bg);
}
.xy-theme__input[type='range']::-moz-range-thumb,
.xy-theme__range::-moz-range-thumb {
width: 1.25rem;
height: 1.25rem;
border: none;
border-radius: 50%;
background: var(--color-primary);
box-shadow: var(--xy-node-boxshadow-default);
}
.xy-theme__input[type='range']::-moz-range-progress,
.xy-theme__range::-moz-range-progress {
height: 0.5rem;
border-radius: 100px 0 0 100px;
background: var(--color-primary-muted);
}
```
##### index.css
```css
@import url('./xy-extras.css');
html,
body {
margin: 0;
font-family: sans-serif;
box-sizing: border-box;
}
#app {
width: 100vw;
height: 100vh;
}
```
##### App.vue
```vue
```
#### Adding nodes
Now that the flow is set up, let's add some nodes. Each node represents an element
placed on the canvas with a specific position and content.
##### Create node objects
In the `