Flow

Use it to show how things are connected and let somebody move them about: the stages of a pipeline, an automation, the parts of a system. Nodes are boxes with your own contents, edges join them, and the canvas is panned and zoomed.

It lays nothing out for you. Every node is given a position, so for a graph whose shape comes from data you need to work the positions out first. For steps in a fixed order with nothing to rearrange, a list of steps is the simpler thing.

Installation

Copy the folder into components/ui, where you can edit it. It needs the cn helper, class-variance-authority, and the theme's info, success and warning colours.

components/ui/flow/
├── Flow.vue
├── FlowBackground.vue … FlowMiniMap.vue
├── context.ts
├── movable.ts
├── flow-paths.ts
└── index.ts

Usage

<script setup lang="ts">
import {
  Flow,
  FlowBackground,
  FlowControls,
  FlowEdge,
  FlowNode,
  FlowNodeContent,
  FlowNodeDescription,
  FlowNodeTitle,
} from "@/components/ui/flow";
</script>

<template>
  <Flow fit-view-on-mount>
    <FlowBackground />
    <FlowNode id="draft" :position="{ x: 40, y: 20 }">
      <FlowNodeContent>
        <FlowNodeTitle>Draft</FlowNodeTitle>
      </FlowNodeContent>
    </FlowNode>
    <FlowNode id="edit" :position="{ x: 40, y: 150 }">
      <FlowNodeContent>
        <FlowNodeTitle>Edit</FlowNodeTitle>
        <FlowNodeDescription>Two rounds</FlowNodeDescription>
      </FlowNodeContent>
    </FlowNode>
    <FlowEdge from="draft" to="edit" arrow />
    <FlowControls />
  </Flow>
</template>

Composition

<Flow>
  <FlowBackground />
  <FlowNode id="…" :position="…">
    <FlowNodeHeader>
      <FlowNodeDescription />
      <FlowNodeBadge />
    </FlowNodeHeader>
    <FlowNodeContent>
      <FlowNodeTitle />
      <FlowNodeDescription />
    </FlowNodeContent>
    <FlowHandle />
  </FlowNode>
  <FlowGroup id="…" :position="…">
    <FlowGroupItem>
      <FlowNodeContent />
    </FlowGroupItem>
  </FlowGroup>
  <FlowEdge from="…" to="…" />
  <FlowControls />
  <FlowMiniMap />
</Flow>

• FlowBackground: the pattern behind the graph, dots, lines or crosses. It moves and scales with the graph.
• FlowNode: a box on the graph. id is what edges call it and position is where it starts. Fill it with the node parts below, or with anything of your own.
• FlowNodeHeader: a strip across the top of a node, ruled off from the rest, with something at each end: a step number and a FlowNodeBadge.
• FlowNodeContent: the body of a node, carrying the node's padding. Inside a FlowGroupItem it has none, because the item has its own.
• FlowNodeTitle: what the node is.
• FlowNodeDescription: a quieter line about the node. It is smaller inside a FlowGroupItem.
• FlowNodeBadge: a word in a pill for the node's state, tinted with the theme colour named by color. muted is grey, and the default.
• FlowHandle: a dot on a node's edge that a connection can be drawn from or dropped on. Give it an id to join an edge to it by name.
• FlowEdge: a line from one node to another: a curve, a routed line or a straight one, optionally dashed, marching and with an arrowhead.
• FlowGroup: a dashed box with a label, round things that belong together. It is dragged as one and an edge can be joined to it.
• FlowGroupItem: one thing inside a group that is not a node of its own: an icon beside a FlowNodeContent. It moves with the group, and edges cannot join it.
• FlowControls: buttons to zoom, fit everything in view and lock the canvas.
• FlowMiniMap: the whole graph, small, with the part in view marked on it.

Edges that pick their own side

An edge with no from-side, to-side or handle leaves from whichever face of its node is turned towards the other one. Drag one node past another and the edges turn to follow. Name the sides when the direction should not change.

A mind map

bezier edges from one centre, each in a theme colour of its own. With no sides named, a branch can be dragged anywhere round the centre.

Wiring it up

A FlowHandle is somewhere to start a connection. Drag from one to another node and @connect is told which two; the edges are yours to keep. is-valid-connection refuses the ones you do not want, here a second wire between the same two steps.

Named ports

FlowHandle takes an id, a face and an offset along it, so one face can hold two. Join an edge to it as "node.handle", and that end stays on the port however the node is dragged. Use ports where the side means something: here accepted leaves from one and rejected from the other.

Building a graph

The canvas holds no list of nodes or edges. Each is something you render, so adding one is adding to an array in your own state.

Moving nodes from outside

position is where a node starts. Keep the positions in state, update them from @node-drag-end, and pass new ones to move the nodes yourself.

Nodes inside a group

A FlowNode inside a FlowGroup is placed relative to the group and moves with it. Give the group a size, because the nodes do not lay it out. confine stops a node's drag at the group's edge. pinned gives the drag to the group, so the node moves only when the group does.

Groups and a minimap

FlowGroup holds ordinary elements and moves as one. The edges are joined to the groups by their id. FlowMiniMap shows where the view is on the whole graph.

API Reference

Every part also takes the attributes of the element it renders, and a class.

Notes

Accessibility

Keyboard shortcuts and ARIA behavior.