Skip to Content
Vue Flow v2 is here and joins xyflow! Read more here →
LearnNuxt

Usage with Nuxt

Nuxt  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:

npm create nuxt@latest my-flow-app

Then install Vue Flow:

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.

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.

app/pages/index.vue
<script setup lang="ts"> import type { Edge, Node } from '@xyflow/vue'; import { shallowRef } from 'vue'; import { Background, Position, VueFlow } from '@xyflow/vue'; const nodes = shallowRef<Node[]>([ { id: '1', position: { x: 40, y: 40 }, data: { label: 'Hello' }, // the server can't measure your nodes, so tell it how big they are width: 100, height: 40, // and where edges are supposed to attach handles: [{ type: 'source', position: Position.Bottom, x: 46, y: 35, width: 8, height: 8 }], }, { id: '2', position: { x: 340, y: 240 }, data: { label: 'World' }, width: 100, height: 40, handles: [{ type: 'target', position: Position.Top, x: 46, y: -3, width: 8, height: 8 }], }, ]); const edges = shallowRef<Edge[]>([{ id: '1->2', source: '1', target: '2' }]); </script> <template> <div style="width: 100vw; height: 100vh"> <VueFlow :nodes="nodes" :edges="edges"> <Background /> </VueFlow> </div> </template>

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:

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:

<template> <div style="width: 800px; height: 400px"> <VueFlow :nodes="nodes" :edges="edges" :width="800" :height="400" fit-view> <Background /> </VueFlow> </div> </template>

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 <VueFlowProvider> or setupVueFlow(), pass them there. On a <VueFlow> inside a provider they’re ignored.

Client-side only

Not every flow has to be in the HTML. Wrap it in Nuxt’s <ClientOnly> and you can skip all of the above:

<template> <ClientOnly> <VueFlow :nodes="nodes" :edges="edges" /> </ClientOnly> </template>

For server side rendering outside of Nuxt, like rendering a flow to an HTML string, check out the server side rendering guide.