);
}
```
### useNodes and useEdges
Subscribe to node/edge state changes. Use sparingly as they cause re-renders on every change.
```tsx
import { useNodes, useEdges } from "@xyflow/react";
function NodeCounter() {
const nodes = useNodes();
const edges = useEdges();
return (
Nodes: {nodes.length}, Edges: {edges.length}
);
}
```
### useNodesState and useEdgesState
Convenience hooks for managing state (good for prototyping):
```tsx
import { useNodesState, useEdgesState } from "@xyflow/react";
const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);
```
### useViewport
Get current viewport state:
```tsx
import { useViewport } from "@xyflow/react";
function ViewportInfo() {
const { x, y, zoom } = useViewport();
return (
);
}
```
### useOnSelectionChange
Listen for selection changes:
```tsx
import { useOnSelectionChange } from "@xyflow/react";
function SelectionListener() {
useOnSelectionChange({
onChange: ({ nodes, edges }) => {
console.log("Selected nodes:", nodes);
console.log("Selected edges:", edges);
},
});
return null;
}
```
## Best Practices
### Performance with React 19
1. **Wrap custom nodes in `memo`**:
```tsx
import { memo } from "react";
import type { Node, NodeProps } from "@xyflow/react";
type MyNodeData = { label: string };
type MyNodeType = Node;
const MyNodeComponent = ({ data }: NodeProps) =>
{data.label}
;
export const MyNode = memo(MyNodeComponent);
```
2. **Define `nodeTypes` outside components**:
```tsx
// GOOD: Outside component
const nodeTypes = { custom: CustomNode };
// BAD: Inside component (causes re-renders)
function Flow() {
const nodeTypes = { custom: CustomNode }; // Creates new object each render
}
```
3. **Memoize callbacks and objects**:
```tsx
const onNodesChange = useCallback(
(changes: NodeChange[]) =>
setNodes((nds) => applyNodeChanges(changes, nds)),
[]
);
const defaultEdgeOptions = useMemo(
() => ({ animated: true, type: "smoothstep" }),
[]
);
```
4. **Use `useReactFlow` instead of `useNodes`/`useEdges`** when you only need to query state occasionally (avoids re-renders):
```tsx
// Better for occasional queries
const reactFlow = useReactFlow();
const handleExport = () => {
const nodes = reactFlow.getNodes();
// export logic
};
```
5. **Use `nodrag` class on interactive elements**:
```tsx
```
### SSR Considerations for Next.js
React Flow uses browser APIs and cannot be server-rendered. Always:
1. Use `"use client"` directive on flow components
2. Dynamically import if needed:
```tsx
import dynamic from "next/dynamic";
const FlowEditor = dynamic(
() => import("@/components/flow/flow-editor").then((mod) => mod.FlowEditor),
{ ssr: false }
);
```
3. Wrap in a client component boundary before using in server components
## Common Patterns
### Preventing Default Drag on Inputs
```tsx
updateNodeData(e.target.value)}
/>
```
### Connecting to Specific Handles
```tsx
// Node with multiple handles
// Edge connecting to specific handle
const edges = [
{ id: 'e1', source: 'node-1', target: 'node-2', sourceHandle: 'output-1' }
];
```
### Saving and Restoring Flow State
```tsx
function FlowWithPersistence() {
const reactFlow = useReactFlow();
const handleSave = () => {
const flow = reactFlow.toObject();
localStorage.setItem("flow", JSON.stringify(flow));
};
const handleRestore = () => {
const saved = localStorage.getItem("flow");
if (saved) {
const flow = JSON.parse(saved);
reactFlow.setNodes(flow.nodes);
reactFlow.setEdges(flow.edges);
reactFlow.setViewport(flow.viewport);
}
};
}
```
## Required Configuration
These settings must **always** be applied to every `` instance:
### 1. Hide Attribution Watermark
```tsx
```
### 2. Dark Mode (next-themes Integration)
React Flow's `colorMode` prop must be synced with next-themes. The `resolvedTheme` is `undefined` during SSR, so use a mounted guard to prevent hydration mismatch:
```tsx
const { resolvedTheme } = useTheme();
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
```
**Why the mounted guard?** `useTheme()` returns `undefined` for `resolvedTheme` on the server. Without the guard, React Flow renders with `colorMode="light"` and then switches to `"dark"` on hydration, causing a flash and a `react-flow light` → `react-flow dark` class mismatch.
### 3. Fit View with Sane Defaults
```tsx
```
Also re-center on window resize:
```tsx
const { fitView } = useReactFlow();
useEffect(() => {
let rafId: number;
const handleResize = () => {
cancelAnimationFrame(rafId);
rafId = requestAnimationFrame(() => {
fitView({ padding: 0.4 });
});
};
window.addEventListener("resize", handleResize);
return () => {
window.removeEventListener("resize", handleResize);
cancelAnimationFrame(rafId);
};
}, [fitView]);
```
### 4. Edge Label z-index for Popovers
Custom edge labels rendered via `EdgeLabelRenderer` sit in a shared layer. If an edge label contains a dropdown/popover, it will render **behind** nodes. Fix by dynamically setting z-index when the menu is open:
```tsx
{/* label pill + dropdown menu */}
```
## Common Issues & Fixes
### TypeScript errors with generic Node types
When using typed node data like `Node[]`, ensure proper generic type handling:
```tsx
type NodeData = { label: string };
// Use generic type parameter on NodeChange
const onNodesChange = useCallback(
(changes: NodeChange>[]) =>
setNodes((nds) => applyNodeChanges(changes, nds)),
[]
);
// Similarly for EdgeChange
const onEdgesChange = useCallback(
(changes: EdgeChange[]) =>
setEdges((eds) => applyEdgeChanges(changes, eds)),
[]
);
```
### Flow canvas appears empty
1. **Check container height**: React Flow requires a parent with defined height
```tsx
// BAD - no height
// GOOD - explicit height
```
2. **Verify CSS import**:
```tsx
import "@xyflow/react/dist/style.css";
```
3. **Check initial viewport**: Use `fitView` prop or call `fitView()` after mount
```tsx
```
### next/dynamic with ssr: false error in Next.js 14+
If using `dynamic` import in a Server Component:
```
Error: `ssr: false` is not allowed with `next/dynamic` in Server Components
```
**Fix**: Add `"use client"` directive to the file using dynamic import:
```tsx
"use client";
import dynamic from "next/dynamic";
const FlowEditor = dynamic(
() => import("@/components/flow/flow-editor").then((mod) => mod.FlowEditor),
{ ssr: false }
);
```
### Nodes not draggable in custom components
Add the `nodrag` class to interactive elements inside custom nodes:
```tsx
```
### useReactFlow returns undefined
Ensure the component is wrapped in `ReactFlowProvider`:
```tsx
// The provider must wrap any component using useReactFlow
{/* useReactFlow works here */}
```
### Build errors with React 19
React Flow v12+ is compatible with React 19. If you encounter issues:
1. Ensure you're using `@xyflow/react` (not the old `reactflow` package)
2. Update to the latest version: `bun add @xyflow/react@latest`
## Resources
- [React Flow Documentation](https://reactflow.dev)
- [React Flow Examples](https://github.com/xyflow/react-flow-example-apps)
- [API Reference](https://reactflow.dev/api-reference)