reactflow-expert

name	reactflow-expert
description	Builds DAG visualizations using ReactFlow v12 with custom nodes, ELKjs auto-layout, Zustand state management, and live state updates via WebSocket. Use when implementing workflow visualization dashboards, creating custom agent node components, integrating ELK layout algorithms, or wiring execution state into React components. Activate on "ReactFlow", "workflow visualization", "DAG visualization", "ELKjs", "custom nodes", "node-based editor", "graph visualization". NOT for writing Mermaid diagrams (use mermaid-graph-writer), general React development, or static diagram rendering.
allowed-tools	Read,Write,Edit,Bash,Grep,Glob
metadata	{"tags":["reactflow","workflow-visualization","dag-visualization"],"pairs-with":[{"skill":"websocket-streaming","reason":"Live DAG state updates flow through WebSocket connections to ReactFlow visualizations"},{"skill":"human-gate-designer","reason":"Human approval gates are rendered as interactive ReactFlow custom nodes"},{"skill":"task-decomposer","reason":"Decomposed task DAGs are visualized as ReactFlow node graphs with ELKjs layout"}]}

ReactFlow Expert

Builds DAG visualizations using ReactFlow v12 with custom agent nodes, ELKjs auto-layout, Zustand state management, and live execution state updates.

---

When to Use

✅ Use for:

• Building workflow/DAG visualization dashboards
• Creating custom ReactFlow node components for agent state
• Integrating ELKjs auto-layout for automatic graph positioning
• Wiring WebSocket execution events into ReactFlow state
• Implementing zoom, pan, selection, and node interaction

❌ NOT for:

• Static Mermaid diagrams (use mermaid-graph-writer)
• General React component development
• Non-graph visualizations (charts, tables)

---

Architecture

flowchart TD
  subgraph "State Layer"
    Z[Zustand Store] --> N[nodes + edges]
    Z --> U[updateNodeData]
    Z --> A[applyNodeChanges / applyEdgeChanges]
  end
  
  subgraph "Layout Layer"
    E[ELKjs] --> P[Compute positions]
    P --> Z
  end
  
  subgraph "Data Layer"
    WS[WebSocket] --> Z
    API[REST API] --> Z
  end
  
  subgraph "Render Layer"
    Z --> RF[ReactFlow component]
    RF --> CN[Custom AgentNode]
    RF --> CE[Custom edges]
    RF --> PA[Panel controls]
  end

---

Core Patterns (ReactFlow v12)

Zustand Store (Recommended over useNodesState for complex editors)

import { create } from 'zustand';
import { applyNodeChanges, applyEdgeChanges, type Node, type Edge } from '@xyflow/react';

interface DAGStore {
  nodes: Node[];
  edges: Edge[];
  onNodesChange: (changes: any) => void;
  onEdgesChange: (changes: any) => void;
  setNodes: (nodes: Node[]) => void;
  setEdges: (edges: Edge[]) => void;
  updateNodeData: (nodeId: string, data: Record<string, any>) => void;
}

const useDAGStore = create<DAGStore>((set, get) => ({
  nodes: [],
  edges: [],
  onNodesChange:  ({ : (changes, ().) }),
  :  ({ : (changes, ().) }),
  :  ({ nodes }),
  :  ({ edges }),
  
  :  ({
    : ()..(
      n. === nodeId ? { ...n, : { ...n., ...data } } : n
    ),
  }),
}));

Custom Agent Node

import { Handle, Position, type NodeProps } from '@xyflow/react';

const STATUS_COLORS = {
  pending: '#9CA3AF', scheduled: '#60A5FA', running: '#3B82F6',
  completed: '#10B981', failed: '#EF4444', retrying: '#F59E0B',
  paused: '#8B5CF6', skipped: '#D1D5DB', mutated: '#EAB308',
};

function AgentNode({ data }: NodeProps) {
  return (
    <div className={`agent-node status-${data.status}`}
         style={{ borderColor: STATUS_COLORS[data.status] }}>
      <Handle type="target" position={Position.Top} />
      <div className="node-header">
        <span =` ${}`} />
        {data.role}
      
      {data.skills && (
        
          {data.skills.map((s: string) => {s})}
        
      )}
      {data.status === 'completed' && data.output?.summary && (
        {data.output.summary.slice(0, 60)}...
      )}
      {data.metrics?.cost_usd > 0 && (
        ${data.metrics.cost_usd.toFixed(3)}
      )}
      
    
  );
}


 nodeTypes = { :  };

ELKjs Auto-Layout Hook

import ELK from 'elkjs/lib/elk.bundled.js';
import { useCallback } from 'react';
import { useReactFlow } from '@xyflow/react';

const elk = new ELK();

export function useAutoLayout() {
  const { fitView } = useReactFlow();

  return useCallback(async (nodes: Node[], edges: Edge[], direction = 'DOWN') => {
    const isHorizontal = direction === 'RIGHT';
    const layouted = await elk.layout({
      id: 'root',
      layoutOptions: {
        'elk.algorithm': 'layered',
        'elk.direction': direction,
        'elk.spacing.nodeNode': '80',
        'elk.layered.spacing.nodeNodeBetweenLayers': '100',
        'elk.edgeRouting': 'ORTHOGONAL',
      },
      children: nodes.map((n) => ({
        ...n,
        targetPosition: isHorizontal ? 'left' : ,
        : isHorizontal ?  : ,
        : n.?. ?? ,
        : n.?. ?? ,
      })),
      edges,
    });
     result = layouted.!.( ({
      ...nodes.( n. === elkN.)!,
      : { : elkN.!, : elkN.! },
    }));
    .( ());
     result;
  }, [fitView]);
}

Dashboard Assembly

import { ReactFlow, ReactFlowProvider, Panel } from '@xyflow/react';
import '@xyflow/react/dist/style.css';

function DAGDashboard({ dagId }: { dagId: string }) {
  const { nodes, edges, onNodesChange, onEdgesChange } = useDAGStore();
  const layout = useAutoLayout();

  // WebSocket → Zustand (see websocket-streaming skill)
  useDAGStream(dagId);

  return (
    <ReactFlow nodes={nodes} edges={edges} nodeTypes={nodeTypes}
      onNodesChange={onNodesChange} onEdgesChange={onEdgesChange} fitView>
      <Panel position="top-right">
        <button onClick={() => layout(nodes, edges, 'DOWN')}>↓ Vertical</button>
        <button onClick={() => layout(nodes, edges, 'RIGHT')}>→ Horizontal</button>
      </Panel>
    </ReactFlow>
  );
}

   () {
   ;
}

---

v12 Gotchas

Pitfall	Fix
nodeTypes defined inside component → infinite re-render	Define OUTSIDE component or wrap in useMemo
State update doesn't trigger re-render	Must create NEW node object: { ...node, data: { ...node.data, ...update } }
xPos/yPos in custom node → undefined	Use positionAbsoluteX/positionAbsoluteY (v12 rename)
nodeInternals → undefined	Use nodeLookup (v12 rename)
ELK layout ignores node size	Pass node.measured?.width and height explicitly
fitView fires before DOM paint	Wrap in requestAnimationFrame(() => fitView())
Interactive elements drag the node	Add className="nodrag" to inputs, buttons, selects

---

Anti-Patterns

Canvas Rendering for Debugging

Wrong: Using canvas-based libraries (GoJS) where you can't inspect nodes in dev tools. Right: ReactFlow renders SVG + HTML. Every node is inspectable in React DevTools and the DOM.

Re-running Layout on Every State Update

Wrong: Calling ELK layout every time a node's status changes (expensive, causes visual jitter). Right: Only re-layout when topology changes (add/remove node/edge). Status color changes are just data updates — no layout needed.

Monolithic Node Component

Wrong: One giant node component handling all node types. Right: Register separate node types: agentNode, humanGateNode, pluripotentNode. Each is a focused React component.