reactflow-fundamentals

What this skill does

# React Flow Fundamentals

Build customizable node-based editors and interactive diagrams with React Flow.
This skill covers core concepts, setup, and common patterns for creating
flow-based interfaces.

## Installation

```bash
# npm
npm install @xyflow/react

# pnpm
pnpm add @xyflow/react

# yarn
yarn add @xyflow/react
```

## Basic Setup

```tsx
import { useCallback } from 'react';
import {
  ReactFlow,
  useNodesState,
  useEdgesState,
  addEdge,
  Background,
  Controls,
  MiniMap,
  type Node,
  type Edge,
  type OnConnect,
} from '@xyflow/react';

import '@xyflow/react/dist/style.css';

const initialNodes: Node[] = [
  {
    id: '1',
    type: 'input',
    data: { label: 'Start' },
    position: { x: 250, y: 0 },
  },
  {
    id: '2',
    data: { label: 'Process' },
    position: { x: 250, y: 100 },
  },
  {
    id: '3',
    type: 'output',
    data: { label: 'End' },
    position: { x: 250, y: 200 },
  },
];

const initialEdges: Edge[] = [
  { id: 'e1-2', source: '1', target: '2' },
  { id: 'e2-3', source: '2', target: '3' },
];

export default function Flow() {
  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);

  const onConnect: OnConnect = useCallback(
    (params) => setEdges((eds) => addEdge(params, eds)),
    [setEdges]
  );

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ReactFlow
        nodes={nodes}
        edges={edges}
        onNodesChange={onNodesChange}
        onEdgesChange={onEdgesChange}
        onConnect={onConnect}
        fitView
      >
        <Background />
        <Controls />
        <MiniMap />
      </ReactFlow>
    </div>
  );
}
```

## Node Types

### Built-in Node Types

```tsx
const nodes: Node[] = [
  // Input node - only has source handles
  {
    id: '1',
    type: 'input',
    data: { label: 'Input Node' },
    position: { x: 0, y: 0 },
  },
  // Default node - has both source and target handles
  {
    id: '2',
    type: 'default',
    data: { label: 'Default Node' },
    position: { x: 0, y: 100 },
  },
  // Output node - only has target handles
  {
    id: '3',
    type: 'output',
    data: { label: 'Output Node' },
    position: { x: 0, y: 200 },
  },
];
```

### Node Configuration

```tsx
const node: Node = {
  id: 'unique-id',
  type: 'default',
  position: { x: 100, y: 100 },
  data: { label: 'My Node', customProp: 'value' },
  // Optional properties
  style: { backgroundColor: '#f0f0f0' },
  className: 'custom-node',
  sourcePosition: Position.Right,
  targetPosition: Position.Left,
  draggable: true,
  selectable: true,
  connectable: true,
  deletable: true,
  hidden: false,
  selected: false,
  dragging: false,
  zIndex: 0,
  extent: 'parent', // Constrain to parent node
  parentId: 'parent-node-id', // For nested nodes
  expandParent: true, // Expand parent when node is outside bounds
};
```

## Edge Types

### Built-in Edge Types

```tsx
import { MarkerType } from '@xyflow/react';

const edges: Edge[] = [
  // Default edge (bezier curve)
  {
    id: 'e1',
    source: '1',
    target: '2',
    type: 'default',
  },
  // Straight line
  {
    id: 'e2',
    source: '2',
    target: '3',
    type: 'straight',
  },
  // Step edge (right angles)
  {
    id: 'e3',
    source: '3',
    target: '4',
    type: 'step',
  },
  // Smoothstep edge (rounded corners)
  {
    id: 'e4',
    source: '4',
    target: '5',
    type: 'smoothstep',
  },
];
```

### Edge Configuration

```tsx
const edge: Edge = {
  id: 'edge-id',
  source: 'source-node-id',
  target: 'target-node-id',
  // Optional properties
  type: 'smoothstep',
  sourceHandle: 'handle-a',
  targetHandle: 'handle-b',
  label: 'Edge Label',
  labelStyle: { fill: '#333', fontWeight: 700 },
  labelBgStyle: { fill: '#fff' },
  labelBgPadding: [8, 4],
  labelBgBorderRadius: 4,
  style: { stroke: '#333', strokeWidth: 2 },
  animated: true,
  markerEnd: {
    type: MarkerType.ArrowClosed,
    color: '#333',
  },
  markerStart: {
    type: MarkerType.Arrow,
  },
  interactionWidth: 20,
  deletable: true,
  selectable: true,
  selected: false,
  hidden: false,
  zIndex: 0,
  data: { customProp: 'value' },
};
```

## Handles

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

function CustomNode({ data }: NodeProps) {
  return (
    <div className="custom-node">
      {/* Target handle (input) */}
      <Handle
        type="target"
        position={Position.Top}
        id="input"
        style={{ background: '#555' }}
        isConnectable={true}
      />

      <div>{data.label}</div>

      {/* Multiple source handles */}
      <Handle
        type="source"
        position={Position.Bottom}
        id="output-a"
        style={{ left: '25%', background: '#555' }}
      />
      <Handle
        type="source"
        position={Position.Bottom}
        id="output-b"
        style={{ left: '75%', background: '#555' }}
      />
    </div>
  );
}
```

## Plugin Components

### Background

```tsx
import { Background, BackgroundVariant } from '@xyflow/react';

<ReactFlow nodes={nodes} edges={edges}>
  {/* Dots pattern */}
  <Background variant={BackgroundVariant.Dots} gap={12} size={1} />

  {/* Lines pattern */}
  <Background variant={BackgroundVariant.Lines} gap={20} />

  {/* Cross pattern */}
  <Background variant={BackgroundVariant.Cross} gap={25} />

  {/* Custom styling */}
  <Background
    color="#aaa"
    gap={16}
    size={1}
    variant={BackgroundVariant.Dots}
  />
</ReactFlow>
```

### Controls

```tsx
import { Controls } from '@xyflow/react';

<ReactFlow nodes={nodes} edges={edges}>
  <Controls
    showZoom={true}
    showFitView={true}
    showInteractive={true}
    position="bottom-left"
  />
</ReactFlow>
```

### MiniMap

```tsx
import { MiniMap } from '@xyflow/react';

<ReactFlow nodes={nodes} edges={edges}>
  <MiniMap
    nodeColor={(node) => {
      switch (node.type) {
        case 'input':
          return '#0041d0';
        case 'output':
          return '#ff0072';
        default:
          return '#1a192b';
      }
    }}
    nodeStrokeWidth={3}
    zoomable
    pannable
  />
</ReactFlow>
```

### Panel

```tsx
import { Panel } from '@xyflow/react';

<ReactFlow nodes={nodes} edges={edges}>
  <Panel position="top-left">
    <button onClick={onSave}>Save</button>
    <button onClick={onRestore}>Restore</button>
  </Panel>

  <Panel position="top-right">
    <div>Node count: {nodes.length}</div>
  </Panel>
</ReactFlow>
```

## Event Handling

```tsx
import {
  ReactFlow,
  type NodeMouseHandler,
  type EdgeMouseHandler,
  type OnSelectionChangeFunc,
} from '@xyflow/react';

function Flow() {
  // Node events
  const onNodeClick: NodeMouseHandler = useCallback((event, node) => {
    console.log('Node clicked:', node.id);
  }, []);

  const onNodeDoubleClick: NodeMouseHandler = useCallback((event, node) => {
    console.log('Node double clicked:', node.id);
  }, []);

  const onNodeDragStart: NodeMouseHandler = useCallback((event, node) => {
    console.log('Drag started:', node.id);
  }, []);

  const onNodeDrag: NodeMouseHandler = useCallback((event, node) => {
    console.log('Dragging:', node.position);
  }, []);

  const onNodeDragStop: NodeMouseHandler = useCallback((event, node) => {
    console.log('Drag stopped:', node.position);
  }, []);

  // Edge events
  const onEdgeClick: EdgeMouseHandler = useCallback((event, edge) => {
    console.log('Edge clicked:', edge.id);
  }, []);

  // Selection changes
  const onSelectionChange: OnSelectionChangeFunc = useCallback(
    ({ nodes, edges }) => {
      console.log('Selected nodes:', nodes);
      console.log('Selected edges:', edges);
    },
    []
  );

  return (
    <ReactFlow
      nodes={nodes}
      edges={edges}
      onNodeClick={onNodeClick}
      onNodeDoubleClick={onNodeDoubleClick}
      onNodeDragStart={onNodeDragStart}
      onNodeDrag={onNodeDrag}
      onNodeDragStop={onNodeDragStop}
      onEdgeClick={onEdgeClick}
      onSel