@hotwirebits/flow

Hotwire Flow

A React Flow recreation using Hotwire (Stimulus + Tailwind CSS). Build node-based editors, workflow builders, DAGs, and org charts with pure HTML — no React required.

Like Lexxy reimagined rich text editing for Rails, Hotwire Flow reimagines node-based graph editors for any web stack.

Features

Feature	Status
Drag & drop nodes	✅
Pan & zoom (scroll, pinch, ctrl+scroll)	✅
SVG edges (bezier, straight, step, smoothstep)	✅
Animated edges	✅
Edge labels (HTML via foreignObject)	✅
Arrow markers	✅
Connection handles (drag to connect)	✅
Node types (input, output, default, group)	✅
Multi-select (shift+click, drag-select box)	✅
Minimap with viewport indicator	✅
Toolbar (zoom in/out, fit view, reset)	✅
Top toolbar bar (save, load, export)	✅
Status bar (zoom, position, node/edge counts)	✅
Background patterns (dots, grid, lines)	✅
DnD sidebar palette	✅
Context menu (right-click)	✅
Keyboard shortcuts (Delete, Ctrl+A, Escape, Space+pan)	✅
Save/Load to localStorage	✅
Data API (addNode, removeNode, getIncomers, getOutgoers, toObject)	✅
NodeResizer (8-handle resize)	✅
NodeToolbar (floating toolbar)	✅
Panel (positioned UI container)	✅
Undo/Redo (Ctrl+Z, Ctrl+Y)	✅
Copy/Paste (Ctrl+C, Ctrl+V)	✅
Smooth viewport animations	✅
fitViewOptions (padding, minZoom, maxZoom)	✅
Auto Layout (vertical/horizontal)	✅
defaultEdgeOptions	✅

Quick Start

npm install @hotwired/stimulus

1. Include CSS

<link rel="stylesheet" href="hotwire-flow.css">

2. Import and register

import { Application } from "@hotwired/stimulus"
import { registerHotwireFlow } from "hotwire-flow"

const app = Application.start()
registerHotwireFlow(app)

3. Write your graph in HTML

<div data-controller="flow" class="hf-canvas" id="canvas">
  <div data-flow-target="pane" class="hf-pane">
    <svg style="position:absolute;top:0;left:0;width:100%;height:100%;overflow:visible;pointer-events:none;z-index:1">
      <path data-controller="flow-edge"
            data-flow-edge-id-value="e1"
            data-flow-edge-source-value="n1"
            data-flow-edge-source-handle-value="n1-r"
            data-flow-edge-target-value="n2"
            data-flow-edge-target-handle-value="n2-l"
            data-flow-edge-type-value="bezier"
            data-flow-edge-animated-value="true"
            data-flow-edge-marker-end-value="arrow"
            class="hf-edge" />
    </svg>
    <div data-flow-target="nodes" class="hf-nodes">
      <!-- Node 1 -->
      <div data-controller="flow-node"
           data-flow-node-id-value="n1"
           data-flow-node-x-value="100" data-flow-node-y-value="200"
           class="hf-node hf-node--input"
           data-action="pointerdown->flow-node#pointerDown click->flow-node#click">
        <div class="hf-node__header">Input</div>
        <div class="hf-node__body">Data source</div>
        <div data-controller="flow-handle"
             data-flow-handle-id-value="n1-r"
             data-flow-handle-node-id-value="n1"
             data-flow-handle-position-value="right"
             class="hf-handle hf-handle--right"
             data-action="pointerdown->flow-handle#pointerDown"></div>
      </div>
      <!-- Node 2 -->
      <div data-controller="flow-node"
           data-flow-node-id-value="n2"
           data-flow-node-x-value="400" data-flow-node-y-value="200"
           class="hf-node hf-node--output"
           data-action="pointerdown->flow-node#pointerDown click->flow-node#click">
        <div data-controller="flow-handle"
             data-flow-handle-id-value="n2-l"
             data-flow-handle-node-id-value="n2"
             data-flow-handle-position-value="left"
             class="hf-handle hf-handle--left"
             data-action="pointerdown->flow-handle#pointerDown"></div>
        <div class="hf-node__header">Output</div>
        <div class="hf-node__body">Result</div>
      </div>
    </div>
  </div>
  <div data-flow-target="selectionBox" class="hf-selection-box"></div>
</div>

Examples

Example	Description
Full Demo	Complete workflow editor with all UI components
DAG Pipeline	6-node ETL data pipeline
Interactive	Dark theme with DnD sidebar, categorized nodes
Save/Load	localStorage persistence
Custom Nodes	Note, Code, Image, Decision node types
Minimap Demo	Large graph with minimap navigation
Minimal	Simplest 2-node setup
Org Chart	B2B company hierarchy
Warehouse	B2B warehouse operations flow
B2B Order	B2B order processing pipeline

Controllers

Controller	Identifier	Purpose
FlowController	flow	Main canvas — pan/zoom/selection/data API
NodeController	flow-node	Node drag/select/position
HandleController	flow-handle	Connection points
EdgeController	flow-edge	SVG paths + labels + markers
ConnectionLineController	flow-connection-line	Live drag connection
MinimapController	flow-minimap	Graph overview
ToolbarController	flow-toolbar	Zoom controls
BackgroundController	flow-background	Dots/grid/lines
ToolbarBarController	flow-toolbar-bar	Top bar (save/export)
StatusBarController	flow-status-bar	Bottom bar (position/counts)
DndNodeController	flow-dnd-node	Drag source
DropzoneController	flow-dropzone	Drop target
ContextMenuController	flow-context-menu	Right-click menu
NodeResizerController	flow-node-resizer	8-handle resize
NodeToolbarController	flow-node-toolbar	Floating node toolbar
PanelController	flow-panel	Positioned panel
LayoutController	flow-layout	Auto-layout (vertical/horizontal)

Class	Purpose
hf-canvas	Canvas container
hf-pane	Transform pane
hf-node	Node base
hf-node--input	Input node (green)
hf-node--default	Default node (blue)
hf-node--output	Output node (red)
hf-node__header	Node header
hf-node__body	Node body
hf-handle	Handle base
hf-handle--top/right/bottom/left	Handle position
hf-edge	Edge SVG path
hf-edge.animated	Animated edge
hf-selection-box	Drag-select box
hf-controls	Zoom controls
hf-toolbar-bar	Top toolbar
hf-status-bar	Bottom status
hf-sidebar	Node palette
hf-minimap	Minimap
hf-context-menu	Right-click menu
hf-panel	Positioned panel

API

const flow = app.getControllerForElementAndIdentifier(canvas, "flow")

// Viewport
flow.zoomIn()
flow.zoomOut()
flow.fitView()
flow.setViewport({ x: 0, y: 0, zoom: 1 })
flow.panBy(100, 50)
flow.setCenter(400, 300, 2)

// Coordinates
const pos = flow.screenToFlow(mouseX, mouseY)
const screen = flow.flowToScreen(flowX, flowY)

// Selection
flow.selectNode("node-1")
flow.clearSelection()

// Data
flow.getNodes()           // [{id, type, position, data}, ...]
flow.getNode("node-1")    // {id, type, position, data}
flow.getIncomers("n2")    // nodes with edges pointing to n2
flow.getOutgoers("n1")    // nodes with edges from n1
flow.toObject()           // {nodes, edges, viewport}
flow.fromObject(state)    // restore state

// Node management
flow.addNode({ id: "n3", type: "default", position: {x:100, y:100} })
flow.removeNode("n1")
flow.addEdge({ id: "e2", source: "n1", target: "n3" })
flow.removeEdge("e1")

Events

All events dispatched on the canvas element with hotwire-flow: prefix:

Event	Detail
ready	{ viewport }
viewportchange	{ viewport }
nodemove	{ nodeId, x, y }
nodeselect	{ nodeId }
nodedragend	{ nodeId }
nodedelete	{ nodeId }
connect	{ sourceNode, sourceHandle, targetNode, targetHandle }
edgeclick	{ edgeId }
edgedelete	{ edgeId }
paneclick	{ position }
contextmenu	{ x, y, nodeId, flowPosition }

Development

npm install
npm run build          # Build CSS
npm test               # Unit + integration tests
npm run test:e2e       # Playwright E2E tests
npm run serve          # Dev server on :3000

License

MIT