react-flow

React Flow

概要

このスキルでは、React Flow（@xyflow/react v12+）を使用して、インタラクティブなノードベース UI を構築、カスタマイズ、デバッグ、最適化します。基本的なセットアップから、計算フロー、サブフロー、外部レイアウトとの連携といった高度なパターンまで扱います。

バージョンとソースに関する方針

@xyflow/react 12.12.0 に基づき、2026-09-28 にガイダンスを確認しています。API を適用する前に、対象プロジェクトにインストールされているバージョンとロックファイルを確認してください。「v12+」であっても、すべてのマイナーリリースにすべての機能が含まれているとは限りません。タスクで変更が必要な場合を除き、プロジェクトの状態とスタイルの選択を維持してください。

特定のガイドや API ページを探すには、公式ドキュメントのインデックスを使用してください。バージョンによって動作が異なる場合は、リリースノートと、インストール済みパッケージの宣言やソースを確認してください。タスクに関連するリファレンスのみを読みます。インポートが省略された例や ... を含む例は、単体で動作するアプリケーションではなく、統合の概要を示すものです。

エージェントの動作契約（以下のルールに従ってください）

1. v12 のプロジェクトでは、@xyflow/react からインポートします。レガシープロジェクトを保守する場合は、移行が作業範囲に含まれるまでは、インストール済みの API に従ってください。
2. スタイルシートを必ずインポートします。import '@xyflow/react/dist/style.css'（デフォルトのビジュアルスタイルを置き換える場合は base.css）を使用します。
3. <ReactFlow> の親コンテナーは、幅と高さが必ず 0 より大きくなるようにしてください（明示的なサイズ指定、またはサイズが設定された flex/grid レイアウトを使用します）。
4. nodeTypes と edgeTypes のオブジェクトは、再レンダリングを防ぐため、コンポーネント本体の外で定義するか、useMemo でラップします。
5. アプリケーション固有のコンテンツやハンドルにはカスタムノードを使用します。シンプルなラベル付きグラフには組み込みノードを使用できます。
6. カスタムノード内のインタラクティブな要素（入力欄、ボタン、セレクト）には nodrag クラスを使用します。
7. カスタムノード内のスクロール可能な要素には nowheel クラスを使用し、ズームへの干渉を防ぎます。
8. ハンドルを非表示にする場合は、visibility: hidden または opacity: 0 を使用します。寸法の計算が機能しなくなるため、display: none は使用しないでください。
9. ノードに同じ種類のハンドルを複数配置する場合は、必ず一意の id プロパティを割り当てます。
10. ハンドルを追加、削除、または再配置した後は、effect 内などで DOM の更新後に useUpdateNodeInternals を呼び出します。
11. ノードやエッジの状態を更新するときは、必ず新しいオブジェクトを作成します。変更は React Flow に検知されません。
12. 複雑なアプリケーションでは、制御フローを優先してください。編集可能な制御要素では onNodesChange と onEdgesChange を接続し、ユーザーが接続を作成できる場合にのみ onConnect を追加します。

最初の 60 秒（初期確認テンプレート）

• リクエストから目的を特定します。新しいフローのセットアップ、カスタムノード／エッジ、状態管理、レイアウト、パフォーマンス、スタイリング、E2E テスト、高度なパターン（元に戻す／やり直し、コピー／貼り付け、計算フロー、コラボレーション）、またはデバッグのいずれかを確認します。
• プロジェクトを調べ、以下の情報を確認します。不足している情報が解決策に影響する場合にのみ、質問してください。
  • React Flow のバージョン（v12+ では @xyflow/react を使用します）
  • TypeScript または JavaScript
  • 状態管理の方法（ローカル状態、Zustand、Redux）
  • 想定されるノード数（パフォーマンス戦略に影響します）
  • スタイリングの方法（CSS、Tailwind、styled-components）
• 速やかに分岐して対応します。
  • レガシー版の reactflow または react-flow-renderer からの移行 → パッケージ名の変更、インポートの変更、API の違い
  • キャンバスが空、またはノードが表示されない → コンテナーのサイズ、または CSS のインポート漏れ
  • エッジが表示されない → ハンドルの不足、CSS の不足、またはハンドルに display: none が設定されている
  • 再レンダリングや動作の遅延 → nodeTypes がコンポーネント内で定義されている、またはメモ化が不足している
  • ノードを接続できない → onConnect ハンドラーまたはハンドル設定の不足
  • レイアウト／配置 → 外部レイアウトライブラリとの連携（dagre、elkjs）
  • 型エラー → Node/Edge 型に対する TypeScript のジェネリックパターン

ルーティングマップ（適切なリファレンスをすばやく確認）

• reactflow または react-flow-renderer から @xyflow/react v12 への移行 -> references/migration.md
• インストール、セットアップ、最初のフロー、ノード／エッジオブジェクト -> references/fundamentals.md
• カスタムノードコンポーネント、Handle、複数のハンドル、ドラッグハンドル -> references/custom-nodes.md
• カスタムエッジコンポーネント、パスユーティリティ、エッジラベル、マーカー -> references/custom-edges.md
• イベントハンドラー、コールバック、接続の検証、選択、キーボード -> references/interactivity.md
• 制御型と非制御型、Zustand 統合、状態更新パターン -> references/state-management.md
• Node／Edge の型、ジェネリクス、共用体型、型ガード -> references/typescript.md
• 外部レイアウトライブラリ（dagre、elkjs、d3）、サブフロー、親子関係 -> references/layouting.md
• 背景、Controls、MiniMap、Panel、NodeToolbar、NodeResizer、フック -> references/components-and-hooks.md
• メモ化、レンダリングの最適化、テーマ設定、CSS 変数、Tailwind -> references/performance-and-styling.md
• キーボード操作、アクセシブルな名前、フォーカス管理、支援技術 -> references/accessibility.md
• サーバーサイドレンダリング、初期ジオメトリ、ハイドレーション、Next.js の境界 -> references/ssr-and-hydration.md
• よくあるエラー、デバッグ、エッジの表示問題、Zustand の警告 -> references/troubleshooting.md
• Playwright の E2E テスト、フローセレクター、ドラッグ／ビューポート／接続のテスト -> references/e2e-testing.md
• 元に戻す／やり直し、コピー／貼り付け、計算済みフロー、動的ハンドル、保存／復元、コラボレーション -> references/advanced-patterns.md
• コンテキストメニューからのノード追加、ドラッグ＆ドロップ式サイドバー、詳細パネル、画像としてエクスポート -> references/recipes.md

よくある落とし穴 -> 次に確認すること

• エラーなしでキャンバスが真っ白 -> 親コンテナに高さがありません。明示的に height: 100vh などを設定してください。
• nodeTypes／edgeTypes の警告 -> オブジェクト定義をコンポーネント本体の外に移動するか、useMemo でラップしてください。
• エッジは描画されるが、位置がずれている -> ハンドルに display: none が使われています。opacity: 0 に変更してください。
• ノード内の入力欄を操作できない -> 操作可能な要素に className="nodrag" を追加してください。
• ドラッグ後にノードが元の位置に戻る -> onNodesChange が接続されていないか、変更が正しく適用されていません。
• 接続線は表示されるが、エッジが作成されない -> onConnect ハンドラーがないか、addEdge を呼び出していません。
• 同じ側にある複数のハンドルが重なる -> CSS（top のオフセット）で位置を調整し、一意の id を割り当ててください。
• 状態の更新がノードに反映されない -> 新しいオブジェクトではなく、ミューテーションを作成しています。スプレッド構文が必要です。
• Zustand のコンテキスト警告 -> @xyflow/react が複数のバージョンでインストールされているか、<ReactFlowProvider> がありません。
• 「Parent node not found」警告とともにサブフローの子がずれた位置に表示される -> nodes 配列で親ノードが子ノードより前にあることを確認してください。

確認チェックリスト

• @xyflow/react/dist/style.css（または base.css とカスタムスタイル）がインポートされていることを確認します。
• 親コンテナの幅と高さがゼロ以外に解決されることを確認します。
• nodeTypes／edgeTypes が安定した参照であること（コンポーネントの外で定義するか、メモ化する）を確認します。
• 接続が必要なカスタムノードに、適切な type、position、ID を持つ <Handle> コンポーネントが使われていることを確認します。
• ノード内の操作可能な要素に nodrag クラスがあることを確認します。
• 制御型フローでは、編集可能な要素に対して onNodesChange／onEdgesChange が接続され、接続の作成が有効な場合は onConnect が接続されていることを確認します。
• 状態の更新で新しいノード／エッジオブジェクトが作成されること（ミューテーションがないこと）を確認します。
• 型安全性のために、フックとコールバックに TypeScript のジェネリクスが適用されていることを確認します。
• パフォーマンスが重要なフローでは、カスタムノード／エッジコンポーネントが React.memo でメモ化されていることを確認します。

例を変更した場合は、スニペット全体の型チェックを行い、実際のブラウザーで該当する操作を試してください。コンパイルだけでは、ハンドル、エッジのジオメトリ、ドラッグ、ビューポート内での表示は検証できません。

References

• references/migration.md
• references/fundamentals.md
• references/custom-nodes.md
• references/custom-edges.md
• references/interactivity.md
• references/state-management.md
• references/typescript.md
• references/layouting.md
• references/components-and-hooks.md
• references/performance-and-styling.md
• references/troubleshooting.md
• references/e2e-testing.md
• references/advanced-patterns.md
• references/recipes.md
• references/accessibility.md
• references/ssr-and-hydration.md