Architectural guidance for building node-based UIs with React Flow. Use when designing flow-based applications, making decisions about state management, integration patterns, or evaluating whether React Flow fits a use case.

React Flow Architecture When to Use React Flow Good Fit Visual programming interfaces Workflow builders and automation tools Diagram editors (flowcharts, org charts) Data pipeline visualization Mind mapping tools Node based audio/video editors Decision tree builders State machine designers Consider Alternatives Simple static diagrams (use SVG or canvas directly) Heavy real time collaboration (may need custom sync layer) 3D visualizations (use Three.js, react three fiber) Graph analysis with 10k+ nodes (use WebGL based solutions like Sigma.js) Decision workflow (gates) Run this sequence before locking the stack or sprinting implementation. Skip only for throwaway prototypes. 1. Name the interactions — List the top user actions (e.g. drag, connect, delete, group). Pass: Each action maps to a concrete React Flow callback you will implement ( onNodesChange , onConnect , …). 2. Classify scale — Estimate peak nodes (visible canvas or document total). Pass: Your range matches a row in [Node Count Guidelines]( node count guidelines) and you accept the listed strategy (e.g. onlyRenderVisibleElements when that row implies it). 3. Place state — Choose local hooks, an external store, or Redux/other. Pass: One sentence states where persistence, undo, or cross surface sync will live, or explicitly “not needed yet.” 4. Re check alternatives — If the use case matches [Consider Alternatives]( consider alternatives), Pass: One sentence explains why React Flow still fits or which listed alternative you chose instead. Architecture Patterns Package Structure (xyflow) Implication : Core logic is framework agnostic. When contributing or debugging, check if issue is in @xyflow/system or framework specific package. State Management Approaches 1. Local State (Simple Apps) Pros : Simple, minimal boilerplate Cons : State isolated to component tree 2. External Store (Production) Pros : State accessible anywhere, easier persistence/sync Cons : More setup, need careful selector optimization 3. Redux/Other State Libraries Data Flow Architecture Sub Flow Pattern (Nested Nodes) Considerations : Use extent: 'parent' to constrain dragging Use expandParent: true to auto expand parent Parent z index affects child rendering order Viewport Persistence Integration Patterns With Backend/API With Layout Algorithms Performance Scaling Node Count Guidelines Nodes Strategy < 100 Default settings 100 500 Enable onlyRenderVisibleElements 500 1000 Simplify custom nodes, reduce DOM elements 1000 Consider virtualization, WebGL alternatives Optimization Techniques Trade offs Controlled vs Uncontrolled Controlled Uncontrolled More boilerplate Less code Full state control Internal state Easy persistence Need toObject() Better for complex apps Good for prototypes Connection Modes Strict (default) Loose Source → Target only Any handle → any handle Predictable behavior More flexible Use for data flows Use for diagrams Edge Rendering Default edges Custom edges Fast rendering More control Limited styling Any SVG/HTML Simple use cases Complex labels

react-flow-architecture