@xyflow/react 12.4.2 → 12.4.3

package/dist/esm/index.mjs

@@ -1,9 +1,9 @@
 "use client"
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
+import { createContext, useContext, useMemo, forwardRef, useEffect, useRef, useState, useLayoutEffect, useCallback, memo } from 'react';
 import cc from 'classcat';
 import { errorMessages, infiniteExtent, isInputDOMNode, getFitViewNodes, getDimensions, fitView, getViewportForBounds, pointToRendererPoint, rendererPointToPoint, isNodeBase, isEdgeBase, getElementsToRemove, isRectObject, nodeToRect, getOverlappingArea, getNodesBounds, evaluateAbsolutePosition, XYPanZoom, PanOnScrollMode, SelectionMode, getEventPosition, getNodesInside, areSetsEqual, XYDrag, snapPosition, calculateNodePosition, Position, ConnectionMode, isMouseEvent, XYHandle, getHostForElement, addEdge, getInternalNodesBounds, isNumeric, nodeHasDimensions, getNodeDimensions, elementSelectionKeys, isEdgeVisible, MarkerType, createMarkerIds, getBezierEdgeCenter, getSmoothStepPath, getStraightPath, getBezierPath, getEdgePosition, getElevatedEdgeZIndex, getMarkerId, getConnectionStatus, ConnectionLineType, updateConnectionLookup, adoptUserNodes, initialConnection, devWarn, updateNodeInternals, updateAbsolutePositions, handleExpandParent, panBy, isMacOs, areConnectionMapsEqual, handleConnectionChange, shallowNodeData, XYMinimap, getBoundsOfRects, ResizeControlVariant, XYResizer, XY_RESIZER_LINE_POSITIONS, XY_RESIZER_HANDLE_POSITIONS, getNodeToolbarTransform } from '@xyflow/system';
 export { ConnectionLineType, ConnectionMode, MarkerType, PanOnScrollMode, Position, ResizeControlVariant, SelectionMode, addEdge, getBezierEdgeCenter, getBezierPath, getConnectedEdges, getEdgeCenter, getIncomers, getNodesBounds, getOutgoers, getSmoothStepPath, getStraightPath, getViewportForBounds, reconnectEdge } from '@xyflow/system';
-import { createContext, useContext, useMemo, forwardRef, useEffect, useRef, useState, useLayoutEffect, useCallback, memo } from 'react';
 import { useStoreWithEqualityFn, createWithEqualityFn } from 'zustand/traditional';
 import { shallow } from 'zustand/shallow';
 import { createPortal } from 'react-dom';
@@ -13,7 +13,9 @@ const Provider$1 = StoreContext.Provider;
 
 const zustandErrorMessage = errorMessages['error001']();
 /**
- * Hook for accessing the internal store. Should only be used in rare cases.
+ * This hook can be used to subscribe to internal state changes of the React Flow
+ * component. The `useStore` hook is re-exported from the [Zustand](https://github.com/pmndrs/zustand)
+ * state management library, so you should check out their docs for more details.
  *
  * @public
  * @param selector
@@ -21,8 +23,13 @@ const zustandErrorMessage = errorMessages['error001']();
  * @returns The selected state slice
  *
  * @example
- * const nodes = useStore((state: ReactFlowState<MyNodeType>) => state.nodes);
+ * ```ts
+ * const nodes = useStore((state) => state.nodes);
+ * ```
  *
+ * @remarks This hook should only be used if there is no other way to access the internal
+ * state. For many of the common use cases, there are dedicated hooks available
+ * such as {@link useReactFlow}, {@link useViewport}, etc.
  */
 function useStore(selector, equalityFn) {
     const store = useContext(StoreContext);
@@ -31,6 +38,20 @@ function useStore(selector, equalityFn) {
     }
     return useStoreWithEqualityFn(store, selector, equalityFn);
 }
+/**
+ * In some cases, you might need to access the store directly. This hook returns the store object which can be used on demand to access the state or dispatch actions.
+ *
+ * @returns The store object
+ *
+ * @example
+ * ```ts
+ * const store = useStoreApi();
+ * ```
+ *
+ * @remarks This hook should only be used if there is no other way to access the internal
+ * state. For many of the common use cases, there are dedicated hooks available
+ * such as {@link useReactFlow}, {@link useViewport}, etc.
+ */
 function useStoreApi() {
     const store = useContext(StoreContext);
     if (store === null) {
@@ -68,11 +89,37 @@ function A11yDescriptions({ rfId, disableKeyboardA11y }) {
 }
 
 const selector$n = (s) => (s.userSelectionActive ? 'none' : 'all');
+/**
+ * The `<Panel />` component helps you position content above the viewport.
+ * It is used internally by the [`<MiniMap />`](/api-reference/components/minimap)
+ * and [`<Controls />`](/api-reference/components/controls) components.
+ *
+ * @public
+ *
+ * @example
+ * ```jsx
+ *import { ReactFlow, Background, Panel } from '@xyflow/react';
+ *
+ *export default function Flow() {
+ *  return (
+ *    <ReactFlow nodes={[]} fitView>
+ *      <Panel position="top-left">top-left</Panel>
+ *      <Panel position="top-center">top-center</Panel>
+ *      <Panel position="top-right">top-right</Panel>
+ *      <Panel position="bottom-left">bottom-left</Panel>
+ *      <Panel position="bottom-center">bottom-center</Panel>
+ *      <Panel position="bottom-right">bottom-right</Panel>
+ *    </ReactFlow>
+ *  );
+ *}
+ *```
+ */
 const Panel = forwardRef(({ position = 'top-left', children, className, style, ...rest }, ref) => {
     const pointerEvents = useStore(selector$n);
     const positionClasses = `${position}`.split('-');
     return (jsx("div", { className: cc(['react-flow__panel', className, ...positionClasses]), style: { ...style, pointerEvents }, ref: ref, ...rest, children: children }));
 });
+Panel.displayName = 'Panel';
 
 function Attribution({ proOptions, position = 'bottom-right' }) {
     if (proOptions?.hideAttribution) {
@@ -200,9 +247,11 @@ const selector$l = (s) => ({
     setPaneClickDistance: s.setPaneClickDistance,
 });
 const initPrevValues = {
-    // these are values that are also passed directly to other components
-    // than the StoreUpdater. We can reduce the number of setStore calls
-    // by setting the same values here as prev fields.
+    /*
+     * these are values that are also passed directly to other components
+     * than the StoreUpdater. We can reduce the number of setStore calls
+     * by setting the same values here as prev fields.
+     */
     translateExtent: infiniteExtent,
     nodeOrigin: defaultNodeOrigin,
     minZoom: 0.5,
@@ -295,38 +344,62 @@ function useColorModeClass(colorMode) {
 
 const defaultDoc = typeof document !== 'undefined' ? document : null;
 /**
- * Hook for handling key events.
+ * This hook lets you listen for specific key codes and tells you whether they are
+ * currently pressed or not.
  *
  * @public
  * @param param.keyCode - The key code (string or array of strings) to use
  * @param param.options - Options
  * @returns boolean
+ *
+ * @example
+ * ```tsx
+ *import { useKeyPress } from '@xyflow/react';
+ *
+ *export default function () {
+ *  const spacePressed = useKeyPress('Space');
+ *  const cmdAndSPressed = useKeyPress(['Meta+s', 'Strg+s']);
+ *
+ *  return (
+ *    <div>
+ *     {spacePressed && <p>Space pressed!</p>}
+ *     {cmdAndSPressed && <p>Cmd + S pressed!</p>}
+ *    </div>
+ *  );
+ *}
+ *```
  */
 function useKeyPress(
-// the keycode can be a string 'a' or an array of strings ['a', 'a+d']
-// a string means a single key 'a' or a combination when '+' is used 'a+d'
-// an array means different possibilites. Explainer: ['a', 'd+s'] here the
-// user can use the single key 'a' or the combination 'd' + 's'
+/*
+ * the keycode can be a string 'a' or an array of strings ['a', 'a+d']
+ * a string means a single key 'a' or a combination when '+' is used 'a+d'
+ * an array means different possibilites. Explainer: ['a', 'd+s'] here the
+ * user can use the single key 'a' or the combination 'd' + 's'
+ */
 keyCode = null, options = { target: defaultDoc, actInsideInputWithModifier: true }) {
     const [keyPressed, setKeyPressed] = useState(false);
     // we need to remember if a modifier key is pressed in order to track it
     const modifierPressed = useRef(false);
     // we need to remember the pressed keys in order to support combinations
     const pressedKeys = useRef(new Set([]));
-    // keyCodes = array with single keys [['a']] or key combinations [['a', 's']]
-    // keysToWatch = array with all keys flattened ['a', 'd', 'ShiftLeft']
-    // used to check if we store event.code or event.key. When the code is in the list of keysToWatch
-    // we use the code otherwise the key. Explainer: When you press the left "command" key, the code is "MetaLeft"
-    // and the key is "Meta". We want users to be able to pass keys and codes so we assume that the key is meant when
-    // we can't find it in the list of keysToWatch.
+    /*
+     * keyCodes = array with single keys [['a']] or key combinations [['a', 's']]
+     * keysToWatch = array with all keys flattened ['a', 'd', 'ShiftLeft']
+     * used to check if we store event.code or event.key. When the code is in the list of keysToWatch
+     * we use the code otherwise the key. Explainer: When you press the left "command" key, the code is "MetaLeft"
+     * and the key is "Meta". We want users to be able to pass keys and codes so we assume that the key is meant when
+     * we can't find it in the list of keysToWatch.
+     */
     const [keyCodes, keysToWatch] = useMemo(() => {
         if (keyCode !== null) {
             const keyCodeArr = Array.isArray(keyCode) ? keyCode : [keyCode];
             const keys = keyCodeArr
                 .filter((kc) => typeof kc === 'string')
-                // we first replace all '+' with '\n'  which we will use to split the keys on
-                // then we replace '\n\n' with '\n+', this way we can also support the combination 'key++'
-                // in the end we simply split on '\n' to get the key array
+                /*
+                 * we first replace all '+' with '\n'  which we will use to split the keys on
+                 * then we replace '\n\n' with '\n+', this way we can also support the combination 'key++'
+                 * in the end we simply split on '\n' to get the key array
+                 */
                 .map((kc) => kc.replace('+', '\n').replace('\n\n', '\n+').split('\n'));
             const keysFlat = keys.reduce((res, item) => res.concat(...item), []);
             return [keys, keysFlat];
@@ -391,12 +464,16 @@ keyCode = null, options = { target: defaultDoc, actInsideInputWithModifier: true
 // utils
 function isMatchingKey(keyCodes, pressedKeys, isUp) {
     return (keyCodes
-        // we only want to compare same sizes of keyCode definitions
-        // and pressed keys. When the user specified 'Meta' as a key somewhere
-        // this would also be truthy without this filter when user presses 'Meta' + 'r'
+        /*
+         * we only want to compare same sizes of keyCode definitions
+         * and pressed keys. When the user specified 'Meta' as a key somewhere
+         * this would also be truthy without this filter when user presses 'Meta' + 'r'
+         */
         .filter((keys) => isUp || keys.length === pressedKeys.size)
-        // since we want to support multiple possibilities only one of the
-        // combinations need to be part of the pressed keys
+        /*
+         * since we want to support multiple possibilities only one of the
+         * combinations need to be part of the pressed keys
+         */
         .some((keys) => keys.every((k) => pressedKeys.has(k))));
 }
 function useKeyOrCode(eventCode, keysToWatch) {
@@ -482,8 +559,8 @@ const useViewportHelper = () => {
                 await panZoom.setViewport(viewport, { duration: options?.duration });
                 return Promise.resolve(true);
             },
-            screenToFlowPosition: (clientPosition, options = { snapToGrid: true }) => {
-                const { transform, snapGrid, domNode } = store.getState();
+            screenToFlowPosition: (clientPosition, options = {}) => {
+                const { transform, snapGrid, snapToGrid, domNode } = store.getState();
                 if (!domNode) {
                     return clientPosition;
                 }
@@ -492,7 +569,9 @@ const useViewportHelper = () => {
                     x: clientPosition.x - domX,
                     y: clientPosition.y - domY,
                 };
-                return pointToRendererPoint(correctedPosition, transform, options.snapToGrid, snapGrid);
+                const _snapGrid = options.snapGrid ?? snapGrid;
+                const _snapToGrid = options.snapToGrid ?? snapToGrid;
+                return pointToRendererPoint(correctedPosition, transform, _snapToGrid, _snapGrid);
             },
             flowToScreenPosition: (flowPosition) => {
                 const { transform, domNode } = store.getState();
@@ -510,13 +589,17 @@ const useViewportHelper = () => {
     }, []);
 };
 
-// This function applies changes to nodes or edges that are triggered by React Flow internally.
-// When you drag a node for example, React Flow will send a position change update.
-// This function then applies the changes and returns the updated elements.
+/*
+ * This function applies changes to nodes or edges that are triggered by React Flow internally.
+ * When you drag a node for example, React Flow will send a position change update.
+ * This function then applies the changes and returns the updated elements.
+ */
 function applyChanges(changes, elements) {
     const updatedElements = [];
-    // By storing a map of changes for each element, we can a quick lookup as we
-    // iterate over the elements array!
+    /*
+     * By storing a map of changes for each element, we can a quick lookup as we
+     * iterate over the elements array!
+     */
     const changesMap = new Map();
     const addItemChanges = [];
     for (const change of changes) {
@@ -525,15 +608,19 @@ function applyChanges(changes, elements) {
             continue;
         }
         else if (change.type === 'remove' || change.type === 'replace') {
-            // For a 'remove' change we can safely ignore any other changes queued for
-            // the same element, it's going to be removed anyway!
+            /*
+             * For a 'remove' change we can safely ignore any other changes queued for
+             * the same element, it's going to be removed anyway!
+             */
             changesMap.set(change.id, [change]);
         }
         else {
             const elementChanges = changesMap.get(change.id);
             if (elementChanges) {
-                // If we have some changes queued already, we can do a mutable update of
-                // that array and save ourselves some copying.
+                /*
+                 * If we have some changes queued already, we can do a mutable update of
+                 * that array and save ourselves some copying.
+                 */
                 elementChanges.push(change);
             }
             else {
@@ -543,8 +630,10 @@ function applyChanges(changes, elements) {
     }
     for (const element of elements) {
         const changes = changesMap.get(element.id);
-        // When there are no changes for an element we can just push it unmodified,
-        // no need to copy it.
+        /*
+         * When there are no changes for an element we can just push it unmodified,
+         * no need to copy it.
+         */
         if (!changes) {
             updatedElements.push(element);
             continue;
@@ -557,17 +646,21 @@ function applyChanges(changes, elements) {
             updatedElements.push({ ...changes[0].item });
             continue;
         }
-        // For other types of changes, we want to start with a shallow copy of the
-        // object so React knows this element has changed. Sequential changes will
-        /// each _mutate_ this object, so there's only ever one copy.
+        /**
+         * For other types of changes, we want to start with a shallow copy of the
+         * object so React knows this element has changed. Sequential changes will
+         * each _mutate_ this object, so there's only ever one copy.
+         */
         const updatedElement = { ...element };
         for (const change of changes) {
             applyChange(change, updatedElement);
         }
         updatedElements.push(updatedElement);
     }
-    // we need to wait for all changes to be applied before adding new items
-    // to be able to add them at the correct index
+    /*
+     * we need to wait for all changes to be applied before adding new items
+     * to be able to add them at the correct index
+     */
     if (addItemChanges.length) {
         addItemChanges.forEach((change) => {
             if (change.index !== undefined) {
@@ -616,22 +709,33 @@ function applyChange(change, element) {
 /**
  * Drop in function that applies node changes to an array of nodes.
  * @public
- * @remarks Various events on the <ReactFlow /> component can produce an {@link NodeChange} that describes how to update the edges of your flow in some way.
- If you don't need any custom behaviour, this util can be used to take an array of these changes and apply them to your edges.
  * @param changes - Array of changes to apply
  * @param nodes - Array of nodes to apply the changes to
  * @returns Array of updated nodes
  * @example
- *  const onNodesChange = useCallback(
-      (changes) => {
-        setNodes((oldNodes) => applyNodeChanges(changes, oldNodes));
-      },
-      [setNodes],
-    );
-  
-    return (
-      <ReactFLow nodes={nodes} edges={edges} onNodesChange={onNodesChange} />
-    );
+ *```tsx
+ *import { useState, useCallback } from 'react';
+ *import { ReactFlow, applyNodeChanges, type Node, type Edge, type OnNodesChange } from '@xyflow/react';
+ *
+ *export default function Flow() {
+ *  const [nodes, setNodes] = useState<Node[]>([]);
+ *  const [edges, setEdges] = useState<Edge[]>([]);
+ *  const onNodesChange: OnNodesChange = useCallback(
+ *    (changes) => {
+ *      setNodes((oldNodes) => applyNodeChanges(changes, oldNodes));
+ *    },
+ *    [setNodes],
+ *  );
+ *
+ *  return (
+ *    <ReactFlow nodes={nodes} edges={edges} onNodesChange={onNodesChange} />
+ *  );
+ *}
+ *```
+ * @remarks Various events on the <ReactFlow /> component can produce an {@link NodeChange}
+ * that describes how to update the edges of your flow in some way.
+ * If you don't need any custom behaviour, this util can be used to take an array
+ * of these changes and apply them to your edges.
  */
 function applyNodeChanges(changes, nodes) {
     return applyChanges(changes, nodes);
@@ -639,22 +743,33 @@ function applyNodeChanges(changes, nodes) {
 /**
  * Drop in function that applies edge changes to an array of edges.
  * @public
- * @remarks Various events on the <ReactFlow /> component can produce an {@link EdgeChange} that describes how to update the edges of your flow in some way.
- If you don't need any custom behaviour, this util can be used to take an array of these changes and apply them to your edges.
  * @param changes - Array of changes to apply
  * @param edges - Array of edge to apply the changes to
  * @returns Array of updated edges
  * @example
+ * ```tsx
+ *import { useState, useCallback } from 'react';
+ *import { ReactFlow, applyEdgeChanges } from '@xyflow/react';
+ *
+ *export default function Flow() {
+ *  const [nodes, setNodes] = useState([]);
+ *  const [edges, setEdges] = useState([]);
  *  const onEdgesChange = useCallback(
-      (changes) => {
-        setEdges((oldEdges) => applyEdgeChanges(changes, oldEdges));
-      },
-      [setEdges],
-    );
-  
-    return (
-      <ReactFlow nodes={nodes} edges={edges} onEdgesChange={onEdgesChange} />
-    );
+ *    (changes) => {
+ *      setEdges((oldEdges) => applyEdgeChanges(changes, oldEdges));
+ *    },
+ *    [setEdges],
+ *  );
+ *
+ *  return (
+ *    <ReactFlow nodes={nodes} edges={edges} onEdgesChange={onEdgesChange} />
+ *  );
+ *}
+ *```
+ * @remarks Various events on the <ReactFlow /> component can produce an {@link EdgeChange}
+ * that describes how to update the edges of your flow in some way.
+ * If you don't need any custom behaviour, this util can be used to take an array
+ * of these changes and apply them to your edges.
  */
 function applyEdgeChanges(changes, edges) {
     return applyChanges(changes, edges);
@@ -673,9 +788,11 @@ function getSelectionChanges(items, selectedIds = new Set(), mutateItem = false)
         // we don't want to set all items to selected=false on the first selection
         if (!(item.selected === undefined && !willBeSelected) && item.selected !== willBeSelected) {
             if (mutateItem) {
-                // this hack is needed for nodes. When the user dragged a node, it's selected.
-                // When another node gets dragged, we need to deselect the previous one,
-                // in order to have only one selected node at a time - the onNodesChange callback comes too late here :/
+                /*
+                 * this hack is needed for nodes. When the user dragged a node, it's selected.
+                 * When another node gets dragged, we need to deselect the previous one,
+                 * in order to have only one selected node at a time - the onNodesChange callback comes too late here :/
+                 */
                 item.selected = willBeSelected;
             }
             changes.push(createSelectionChange(item.id, willBeSelected));
@@ -712,22 +829,46 @@ function elementToRemoveChange(item) {
 }
 
 /**
- * Test whether an object is useable as a Node
+ * Test whether an object is useable as an [`Node`](/api-reference/types/node).
+ * In TypeScript this is a type guard that will narrow the type of whatever you pass in to
+ * [`Node`](/api-reference/types/node) if it returns `true`.
+ *
  * @public
  * @remarks In TypeScript this is a type guard that will narrow the type of whatever you pass in to Node if it returns true
  * @param element - The element to test
  * @returns A boolean indicating whether the element is an Node
+ *
+ * @example
+ * ```js
+ *import { isNode } from '@xyflow/react';
+ *
+ *if (isNode(node)) {
+ * // ..
+ *}
+ *```
  */
 const isNode = (element) => isNodeBase(element);
 /**
- * Test whether an object is useable as an Edge
+ * Test whether an object is useable as an [`Edge`](/api-reference/types/edge).
+ * In TypeScript this is a type guard that will narrow the type of whatever you pass in to
+ * [`Edge`](/api-reference/types/edge) if it returns `true`.
+ *
  * @public
  * @remarks In TypeScript this is a type guard that will narrow the type of whatever you pass in to Edge if it returns true
  * @param element - The element to test
  * @returns A boolean indicating whether the element is an Edge
+ *
+ * @example
+ * ```js
+ *import { isEdge } from '@xyflow/react';
+ *
+ *if (isEdge(edge)) {
+ * // ..
+ *}
+ *```
  */
 const isEdge = (element) => isEdgeBase(element);
-// eslint-disable-next-line @typescript-eslint/ban-types
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
 function fixedForwardRef(render) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return forwardRef(render);
@@ -745,19 +886,25 @@ const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffec
  * @returns a Queue object
  */
 function useQueue(runQueue) {
-    // Because we're using a ref above, we need some way to let React know when to
-    // actually process the queue. We increment this number any time we mutate the
-    // queue, creating a new state to trigger the layout effect below.
-    // Using a boolean dirty flag here instead would lead to issues related to
-    // automatic batching. (https://github.com/xyflow/xyflow/issues/4779)
+    /*
+     * Because we're using a ref above, we need some way to let React know when to
+     * actually process the queue. We increment this number any time we mutate the
+     * queue, creating a new state to trigger the layout effect below.
+     * Using a boolean dirty flag here instead would lead to issues related to
+     * automatic batching. (https://github.com/xyflow/xyflow/issues/4779)
+     */
     const [serial, setSerial] = useState(BigInt(0));
-    // A reference of all the batched updates to process before the next render. We
-    // want a reference here so multiple synchronous calls to `setNodes` etc can be
-    // batched together.
+    /*
+     * A reference of all the batched updates to process before the next render. We
+     * want a reference here so multiple synchronous calls to `setNodes` etc can be
+     * batched together.
+     */
     const [queue] = useState(() => createQueue(() => setSerial(n => n + BigInt(1))));
-    // Layout effects are guaranteed to run before the next render which means we
-    // shouldn't run into any issues with stale state or weird issues that come from
-    // rendering things one frame later than expected (we used to use `setTimeout`).
+    /*
+     * Layout effects are guaranteed to run before the next render which means we
+     * shouldn't run into any issues with stale state or weird issues that come from
+     * rendering things one frame later than expected (we used to use `setTimeout`).
+     */
     useIsomorphicLayoutEffect(() => {
         const queueItems = queue.get();
         if (queueItems.length) {
@@ -792,9 +939,11 @@ function BatchProvider({ children, }) {
     const store = useStoreApi();
     const nodeQueueHandler = useCallback((queueItems) => {
         const { nodes = [], setNodes, hasDefaultNodes, onNodesChange, nodeLookup } = store.getState();
-        // This is essentially an `Array.reduce` in imperative clothing. Processing
-        // this queue is a relatively hot path so we'd like to avoid the overhead of
-        // array methods where we can.
+        /*
+         * This is essentially an `Array.reduce` in imperative clothing. Processing
+         * this queue is a relatively hot path so we'd like to avoid the overhead of
+         * array methods where we can.
+         */
         let next = nodes;
         for (const payload of queueItems) {
             next = typeof payload === 'function' ? payload(next) : payload;
@@ -840,10 +989,33 @@ function useBatchContext() {
 
 const selector$k = (s) => !!s.panZoom;
 /**
- * Hook for accessing the ReactFlow instance.
+ * This hook returns a ReactFlowInstance that can be used to update nodes and edges, manipulate the viewport, or query the current state of the flow.
  *
  * @public
  * @returns ReactFlowInstance
+ *
+ * @example
+ * ```jsx
+ *import { useCallback, useState } from 'react';
+ *import { useReactFlow } from '@xyflow/react';
+ *
+ *export function NodeCounter() {
+ *  const reactFlow = useReactFlow();
+ *  const [count, setCount] = useState(0);
+ *  const countNodes = useCallback(() => {
+ *    setCount(reactFlow.getNodes().length);
+ *    // you need to pass it as a dependency if you are using it with useEffect or useCallback
+ *    // because at the first render, it's not initialized yet and some functions might not work.
+ *  }, [reactFlow]);
+ *
+ *  return (
+ *    <div>
+ *      <button onClick={countNodes}>Update count</button>
+ *      <p>There are {count} nodes in the flow.</p>
+ *    </div>
+ *  );
+ *}
+ *```
  */
 function useReactFlow() {
     const viewportHelper = useViewportHelper();
@@ -1310,8 +1482,10 @@ function Pane({ isSelecting, selectionKeyPressed, selectionMode = SelectionMode.
         }
         event.target?.releasePointerCapture?.(event.pointerId);
         const { userSelectionRect } = store.getState();
-        // We only want to trigger click functions when in selection mode if
-        // the user did not move the mouse.
+        /*
+         * We only want to trigger click functions when in selection mode if
+         * the user did not move the mouse.
+         */
         if (!userSelectionActive && userSelectionRect && event.target === container.current) {
             onClick?.(event);
         }
@@ -1321,8 +1495,10 @@ function Pane({ isSelecting, selectionKeyPressed, selectionMode = SelectionMode.
             nodesSelectionActive: selectedNodeIds.current.size > 0,
         });
         onSelectionEnd?.(event);
-        // If the user kept holding the selectionKey during the selection,
-        // we need to reset the selectionInProgress, so the next click event is not prevented
+        /*
+         * If the user kept holding the selectionKey during the selection,
+         * we need to reset the selectionInProgress, so the next click event is not prevented
+         */
         if (selectionKeyPressed || selectionOnDrag) {
             selectionInProgress.current = false;
         }
@@ -1332,10 +1508,12 @@ function Pane({ isSelecting, selectionKeyPressed, selectionMode = SelectionMode.
     return (jsxs("div", { className: cc(['react-flow__pane', { draggable, dragging, selection: isSelecting }]), onClick: hasActiveSelection ? undefined : wrapHandler(onClick, container), onContextMenu: wrapHandler(onContextMenu, container), onWheel: wrapHandler(onWheel, container), onPointerEnter: hasActiveSelection ? undefined : onPaneMouseEnter, onPointerDown: hasActiveSelection ? onPointerDown : onPaneMouseMove, onPointerMove: hasActiveSelection ? onPointerMove : onPaneMouseMove, onPointerUp: hasActiveSelection ? onPointerUp : undefined, onPointerLeave: onPaneMouseLeave, ref: container, style: containerStyle, children: [children, jsx(UserSelection, {})] }));
 }
 
-// this handler is called by
-// 1. the click handler when node is not draggable or selectNodesOnDrag = false
-// or
-// 2. the on drag start handler when node is draggable and selectNodesOnDrag = true
+/*
+ * this handler is called by
+ * 1. the click handler when node is not draggable or selectNodesOnDrag = false
+ * or
+ * 2. the on drag start handler when node is draggable and selectNodesOnDrag = true
+ */
 function handleNodeClick({ id, store, unselect = false, nodeRef, }) {
     const { addSelectedNodes, unselectNodesAndEdges, multiSelectionActive, nodeLookup, onError } = store.getState();
     const node = nodeLookup.get(id);
@@ -1414,8 +1592,10 @@ function useMoveSelectedNodes() {
         const { nodeExtent, snapToGrid, snapGrid, nodesDraggable, onError, updateNodePositions, nodeLookup, nodeOrigin } = store.getState();
         const nodeUpdates = new Map();
         const isSelected = selectedAndDraggable(nodesDraggable);
-        // by default a node moves 5px on each key press
-        // if snap grid is enabled, we use that for the velocity
+        /*
+         * by default a node moves 5px on each key press
+         * if snap grid is enabled, we use that for the velocity
+         */
         const xVelo = snapToGrid ? snapGrid[0] : 5;
         const yVelo = snapToGrid ? snapGrid[1] : 5;
         const xDiff = params.direction.x * xVelo * params.factor;
@@ -1451,6 +1631,34 @@ function useMoveSelectedNodes() {
 const NodeIdContext = createContext(null);
 const Provider = NodeIdContext.Provider;
 NodeIdContext.Consumer;
+/**
+ * You can use this hook to get the id of the node it is used inside. It is useful
+ * if you need the node's id deeper in the render tree but don't want to manually
+ * drill down the id as a prop.
+ *
+ * @public
+ * @returns id of the node
+ *
+ * @example
+ *```jsx
+ *import { useNodeId } from '@xyflow/react';
+ *
+ *export default function CustomNode() {
+ *  return (
+ *    <div>
+ *      <span>This node has an id of </span>
+ *      <NodeIdDisplay />
+ *    </div>
+ *  );
+ *}
+ *
+ *function NodeIdDisplay() {
+ *  const nodeId = useNodeId();
+ *
+ *  return <span>{nodeId}</span>;
+ *}
+ *```
+ */
 const useNodeId = () => {
     const nodeId = useContext(NodeIdContext);
     return nodeId;
@@ -1590,8 +1798,10 @@ function HandleComponent({ type = 'source', position = Position.Top, isValidConn
                 connectingfrom: connectingFrom,
                 connectingto: connectingTo,
                 valid,
-                // shows where you can start a connection from
-                // and where you can end it while connecting
+                /*
+                 * shows where you can start a connection from
+                 * and where you can end it while connecting
+                 */
                 connectionindicator: isConnectable &&
                     (!connectionInProcess || isPossibleEndHandle) &&
                     (connectionInProcess ? isConnectableEnd : isConnectableStart),
@@ -1599,7 +1809,29 @@ function HandleComponent({ type = 'source', position = Position.Top, isValidConn
         ]), onMouseDown: onPointerDown, onTouchStart: onPointerDown, onClick: connectOnClick ? onClick : undefined, ref: ref, ...rest, children: children }));
 }
 /**
- * The Handle component is a UI element that is used to connect nodes.
+ * The `<Handle />` component is used in your [custom nodes](/learn/customization/custom-nodes)
+ * to define connection points.
+ *
+ *@public
+ *
+ *@example
+ *
+ *```jsx
+ *import { Handle, Position } from '@xyflow/react';
+ *
+ *export function CustomNode({ data }) {
+ *  return (
+ *    <>
+ *      <div style={{ padding: '10px 20px' }}>
+ *        {data.label}
+ *      </div>
+ *
+ *      <Handle type="target" position={Position.Left} />
+ *      <Handle type="source" position={Position.Right} />
+ *    </>
+ *  );
+ *};
+ *```
  */
 const Handle = memo(fixedForwardRef(HandleComponent));
 
@@ -1792,8 +2024,10 @@ function useNodeObserver({ node, nodeType, hasDimensions, resizeObserver, }) {
     }, []);
     useEffect(() => {
         if (nodeRef.current) {
-            // when the user programmatically changes the source or handle position, we need to update the internals
-            // to make sure the edges are updated correctly
+            /*
+             * when the user programmatically changes the source or handle position, we need to update the internals
+             * to make sure the edges are updated correctly
+             */
             const typeChanged = prevType.current !== nodeType;
             const sourcePosChanged = prevSourcePosition.current !== node.sourcePosition;
             const targetPosChanged = prevTargetPosition.current !== node.targetPosition;
@@ -1810,7 +2044,7 @@ function useNodeObserver({ node, nodeType, hasDimensions, resizeObserver, }) {
     return nodeRef;
 }
 
-function NodeWrapper({ id, onClick, onMouseEnter, onMouseMove, onMouseLeave, onContextMenu, onDoubleClick, nodesDraggable, elementsSelectable, nodesConnectable, nodesFocusable, resizeObserver, noDragClassName, noPanClassName, disableKeyboardA11y, rfId, nodeTypes, nodeExtent, nodeClickDistance, onError, }) {
+function NodeWrapper({ id, onClick, onMouseEnter, onMouseMove, onMouseLeave, onContextMenu, onDoubleClick, nodesDraggable, elementsSelectable, nodesConnectable, nodesFocusable, resizeObserver, noDragClassName, noPanClassName, disableKeyboardA11y, rfId, nodeTypes, nodeClickDistance, onError, }) {
     const { node, internals, isParent } = useStore((s) => {
         const node = s.nodeLookup.get(id);
         const isParent = s.parentLookup.has(id);
@@ -1868,8 +2102,10 @@ function NodeWrapper({ id, onClick, onMouseEnter, onMouseMove, onMouseLeave, onC
     const onSelectNodeHandler = (event) => {
         const { selectNodesOnDrag, nodeDragThreshold } = store.getState();
         if (isSelectable && (!selectNodesOnDrag || !isDraggable || nodeDragThreshold > 0)) {
-            // this handler gets called by XYDrag on drag start when selectNodesOnDrag=true
-            // here we only need to call it when selectNodesOnDrag=false
+            /*
+             * this handler gets called by XYDrag on drag start when selectNodesOnDrag=true
+             * here we only need to call it when selectNodesOnDrag=false
+             */
             handleNodeClick({
                 id,
                 store,
@@ -1945,29 +2181,31 @@ function NodeRendererComponent(props) {
     const resizeObserver = useResizeObserver();
     return (jsx("div", { className: "react-flow__nodes", style: containerStyle, children: nodeIds.map((nodeId) => {
             return (
-            // The split of responsibilities between NodeRenderer and
-            // NodeComponentWrapper may appear weird. However, it’s designed to
-            // minimize the cost of updates when individual nodes change.
-            //
-            // For example, when you’re dragging a single node, that node gets
-            // updated multiple times per second. If `NodeRenderer` were to update
-            // every time, it would have to re-run the `nodes.map()` loop every
-            // time. This gets pricey with hundreds of nodes, especially if every
-            // loop cycle does more than just rendering a JSX element!
-            //
-            // As a result of this choice, we took the following implementation
-            // decisions:
-            // - NodeRenderer subscribes *only* to node IDs – and therefore
-            //   rerender *only* when visible nodes are added or removed.
-            // - NodeRenderer performs all operations the result of which can be
-            //   shared between nodes (such as creating the `ResizeObserver`
-            //   instance, or subscribing to `selector`). This means extra prop
-            //   drilling into `NodeComponentWrapper`, but it means we need to run
-            //   these operations only once – instead of once per node.
-            // - Any operations that you’d normally write inside `nodes.map` are
-            //   moved into `NodeComponentWrapper`. This ensures they are
-            //   memorized – so if `NodeRenderer` *has* to rerender, it only
-            //   needs to regenerate the list of nodes, nothing else.
+            /*
+             * The split of responsibilities between NodeRenderer and
+             * NodeComponentWrapper may appear weird. However, it’s designed to
+             * minimize the cost of updates when individual nodes change.
+             *
+             * For example, when you’re dragging a single node, that node gets
+             * updated multiple times per second. If `NodeRenderer` were to update
+             * every time, it would have to re-run the `nodes.map()` loop every
+             * time. This gets pricey with hundreds of nodes, especially if every
+             * loop cycle does more than just rendering a JSX element!
+             *
+             * As a result of this choice, we took the following implementation
+             * decisions:
+             * - NodeRenderer subscribes *only* to node IDs – and therefore
+             *   rerender *only* when visible nodes are added or removed.
+             * - NodeRenderer performs all operations the result of which can be
+             *   shared between nodes (such as creating the `ResizeObserver`
+             *   instance, or subscribing to `selector`). This means extra prop
+             *   drilling into `NodeComponentWrapper`, but it means we need to run
+             *   these operations only once – instead of once per node.
+             * - Any operations that you’d normally write inside `nodes.map` are
+             *   moved into `NodeComponentWrapper`. This ensures they are
+             *   memorized – so if `NodeRenderer` *has* to rerender, it only
+             *   needs to regenerate the list of nodes, nothing else.
+             */
             jsx(NodeWrapper, { id: nodeId, nodeTypes: props.nodeTypes, nodeExtent: props.nodeExtent, onClick: props.onNodeClick, onMouseEnter: props.onNodeMouseEnter, onMouseMove: props.onNodeMouseMove, onMouseLeave: props.onNodeMouseLeave, onContextMenu: props.onNodeContextMenu, onDoubleClick: props.onNodeDoubleClick, noDragClassName: props.noDragClassName, noPanClassName: props.noPanClassName, rfId: props.rfId, disableKeyboardA11y: props.disableKeyboardA11y, resizeObserver: resizeObserver, nodesDraggable: nodesDraggable, nodesConnectable: nodesConnectable, nodesFocusable: nodesFocusable, elementsSelectable: elementsSelectable, nodeClickDistance: props.nodeClickDistance, onError: onError }, nodeId));
         }) }));
 }
@@ -2046,9 +2284,11 @@ const Marker = ({ id, type, color, width = 12.5, height = 12.5, markerUnits = 's
     }
     return (jsx("marker", { className: "react-flow__arrowhead", id: id, markerWidth: `${width}`, markerHeight: `${height}`, viewBox: "-10 -10 20 20", markerUnits: markerUnits, orient: orient, refX: "0", refY: "0", children: jsx(Symbol, { color: color, strokeWidth: strokeWidth }) }));
 };
-// when you have multiple flows on a page and you hide the first one, the other ones have no markers anymore
-// when they do have markers with the same ids. To prevent this the user can pass a unique id to the react flow wrapper
-// that we can then use for creating our unique marker ids
+/*
+ * when you have multiple flows on a page and you hide the first one, the other ones have no markers anymore
+ * when they do have markers with the same ids. To prevent this the user can pass a unique id to the react flow wrapper
+ * that we can then use for creating our unique marker ids
+ */
 const MarkerDefinitions = ({ defaultColor, rfId }) => {
     const edges = useStore((s) => s.edges);
     const defaultEdgeOptions = useStore((s) => s.defaultEdgeOptions);
@@ -2090,8 +2330,61 @@ function EdgeTextComponent({ x, y, label, labelStyle = {}, labelShowBg = true, l
     return (jsxs("g", { transform: `translate(${x - edgeTextBbox.width / 2} ${y - edgeTextBbox.height / 2})`, className: edgeTextClasses, visibility: edgeTextBbox.width ? 'visible' : 'hidden', ...rest, children: [labelShowBg && (jsx("rect", { width: edgeTextBbox.width + 2 * labelBgPadding[0], x: -labelBgPadding[0], y: -labelBgPadding[1], height: edgeTextBbox.height + 2 * labelBgPadding[1], className: "react-flow__edge-textbg", style: labelBgStyle, rx: labelBgBorderRadius, ry: labelBgBorderRadius })), jsx("text", { className: "react-flow__edge-text", y: edgeTextBbox.height / 2, dy: "0.3em", ref: edgeTextRef, style: labelStyle, children: label }), children] }));
 }
 EdgeTextComponent.displayName = 'EdgeText';
+/**
+ * You can use the `<EdgeText />` component as a helper component to display text
+ * within your custom edges.
+ *
+ *@public
+ *
+ *@example
+ *```jsx
+ *import { EdgeText } from '@xyflow/react';
+ *
+ *export function CustomEdgeLabel({ label }) {
+ *  return (
+ *    <EdgeText
+ *      x={100}
+ *      y={100}
+ *      label={label}
+ *      labelStyle={{ fill: 'white' }}
+ *      labelShowBg
+ *      labelBgStyle={{ fill: 'red' }}
+ *      labelBgPadding={[2, 4]}
+ *      labelBgBorderRadius={2}
+ *    />
+ *  );
+ *}
+ *```
+ */
 const EdgeText = memo(EdgeTextComponent);
 
+/**
+ * The `<BaseEdge />` component gets used internally for all the edges. It can be
+ * used inside a custom edge and handles the invisible helper edge and the edge label
+ * for you.
+ *
+ * @public
+ * @example
+ * ```jsx
+ *import { BaseEdge } from '@xyflow/react';
+ *
+ *export function CustomEdge({ sourceX, sourceY, targetX, targetY, ...props }) {
+ *  const [edgePath] = getStraightPath({
+ *    sourceX,
+ *    sourceY,
+ *    targetX,
+ *    targetY,
+ *  });
+ *
+ *  return <BaseEdge path={edgePath} {...props} />;
+ *}
+ *```
+ *
+ * @remarks If you want to use an edge marker with the [`<BaseEdge />`](/api-reference/components/base-edge) component,
+ * you can pass the `markerStart` or `markerEnd` props passed to your custom edge
+ * through to the [`<BaseEdge />`](/api-reference/components/base-edge) component.
+ * You can see all the props passed to a custom edge by looking at the [`EdgeProps`](/api-reference/types/edge-props) type.
+ */
 function BaseEdge({ path, labelX, labelY, label, labelStyle, labelShowBg, labelBgStyle, labelBgPadding, labelBgBorderRadius, interactionWidth = 20, ...props }) {
     return (jsxs(Fragment, { children: [jsx("path", { ...props, d: path, fill: "none", className: cc(['react-flow__edge-path', props.className]) }), interactionWidth && (jsx("path", { d: path, fill: "none", strokeOpacity: 0, strokeWidth: interactionWidth, className: "react-flow__edge-interaction" })), label && isNumeric(labelX) && isNumeric(labelY) ? (jsx(EdgeText, { x: labelX, y: labelY, label: label, labelStyle: labelStyle, labelShowBg: labelShowBg, labelBgStyle: labelBgStyle, labelBgPadding: labelBgPadding, labelBgBorderRadius: labelBgBorderRadius })) : null] }));
 }
@@ -2102,6 +2395,11 @@ function getControl({ pos, x1, y1, x2, y2 }) {
     }
     return [x1, 0.5 * (y1 + y2)];
 }
+/**
+ * The `getSimpleBezierPath` util returns everything you need to render a simple
+ * bezier edge between two nodes.
+ * @public
+ */
 function getSimpleBezierPath({ sourceX, sourceY, sourcePosition = Position.Bottom, targetX, targetY, targetPosition = Position.Top, }) {
     const [sourceControlX, sourceControlY] = getControl({
         pos: sourcePosition,
@@ -2502,9 +2800,28 @@ function getSelector(connectionSelector) {
     return storeSelector$1;
 }
 /**
- * Hook for accessing the connection state.
+ * The `useConnection` hook returns the current connection when there is an active
+ * connection interaction. If no connection interaction is active, it returns null
+ * for every property. A typical use case for this hook is to colorize handles
+ * based on a certain condition (e.g. if the connection is valid or not).
  *
  * @public
+ * @example
+ *
+ * ```tsx
+ *import { useConnection } from '@xyflow/react';
+ *
+ *function App() {
+ *  const connection = useConnection();
+ *
+ *  return (
+ *    <div> {connection ? `Someone is trying to make a connection from ${connection.fromNode} to this one.` : 'There are currently no incoming connections!'}
+ *
+ *   </div>
+ *   );
+ * }
+ * ```
+ *
  * @returns ConnectionState
  */
 function useConnection(connectionSelector) {
@@ -2519,7 +2836,7 @@ const selector$7 = (s) => ({
     width: s.width,
     height: s.height,
 });
-function ConnectionLineWrapper({ containerStyle, style, type, component }) {
+function ConnectionLineWrapper({ containerStyle, style, type, component, }) {
     const { nodesConnectable, width, height, isValid, inProgress } = useStore(selector$7, shallow);
     const renderConnection = !!(width && nodesConnectable && inProgress);
     if (!renderConnection) {
@@ -2527,7 +2844,7 @@ function ConnectionLineWrapper({ containerStyle, style, type, component }) {
     }
     return (jsx("svg", { style: containerStyle, width: width, height: height, className: "react-flow__connectionline react-flow__container", children: jsx("g", { className: cc(['react-flow__connection', getConnectionStatus(isValid)]), children: jsx(ConnectionLine, { style: style, type: type, CustomComponent: component, isValid: isValid }) }) }));
 }
-const ConnectionLine = ({ style, type = ConnectionLineType.Bezier, CustomComponent, isValid }) => {
+const ConnectionLine = ({ style, type = ConnectionLineType.Bezier, CustomComponent, isValid, }) => {
     const { inProgress, from, fromNode, fromHandle, fromPosition, to, toNode, toHandle, toPosition } = useConnection();
     if (!inProgress) {
         return;
@@ -2700,12 +3017,14 @@ const createStore = ({ nodes, edges, defaultNodes, defaultEdges, width, height,
     ...getInitialState({ nodes, edges, width, height, fitView: fitView$1, nodeOrigin, nodeExtent, defaultNodes, defaultEdges }),
     setNodes: (nodes) => {
         const { nodeLookup, parentLookup, nodeOrigin, elevateNodesOnSelect } = get();
-        // setNodes() is called exclusively in response to user actions:
-        // - either when the `<ReactFlow nodes>` prop is updated in the controlled ReactFlow setup,
-        // - or when the user calls something like `reactFlowInstance.setNodes()` in an uncontrolled ReactFlow setup.
-        //
-        // When this happens, we take the note objects passed by the user and extend them with fields
-        // relevant for internal React Flow operations.
+        /*
+         * setNodes() is called exclusively in response to user actions:
+         * - either when the `<ReactFlow nodes>` prop is updated in the controlled ReactFlow setup,
+         * - or when the user calls something like `reactFlowInstance.setNodes()` in an uncontrolled ReactFlow setup.
+         *
+         * When this happens, we take the note objects passed by the user and extend them with fields
+         * relevant for internal React Flow operations.
+         */
         adoptUserNodes(nodes, nodeLookup, parentLookup, {
             nodeOrigin,
             nodeExtent,
@@ -2731,9 +3050,11 @@ const createStore = ({ nodes, edges, defaultNodes, defaultEdges, width, height,
             set({ hasDefaultEdges: true });
         }
     },
-    // Every node gets registerd at a ResizeObserver. Whenever a node
-    // changes its dimensions, this function is called to measure the
-    // new dimensions and update the nodes.
+    /*
+     * Every node gets registerd at a ResizeObserver. Whenever a node
+     * changes its dimensions, this function is called to measure the
+     * new dimensions and update the nodes.
+     */
     updateNodeInternals: (updates, params = { triggerFitView: true }) => {
         const { triggerNodeChanges, nodeLookup, parentLookup, fitViewOnInit, fitViewDone, fitViewOnInitOptions, domNode, nodeOrigin, nodeExtent, debug, fitViewSync, } = get();
         const { changes, updatedInternals } = updateNodeInternals(updates, nodeLookup, parentLookup, domNode, nodeOrigin, nodeExtent);
@@ -2750,11 +3071,13 @@ const createStore = ({ nodes, edges, defaultNodes, defaultEdges, width, height,
                     nodes: fitViewOnInitOptions?.nodes,
                 });
             }
-            // here we are cirmumventing the onNodesChange handler
-            // in order to be able to display nodes even if the user
-            // has not provided an onNodesChange handler.
-            // Nodes are only rendered if they have a width and height
-            // attribute which they get from this handler.
+            /*
+             * here we are cirmumventing the onNodesChange handler
+             * in order to be able to display nodes even if the user
+             * has not provided an onNodesChange handler.
+             * Nodes are only rendered if they have a width and height
+             * attribute which they get from this handler.
+             */
             set({ fitViewDone: nextFitViewDone });
         }
         else {
@@ -2857,8 +3180,10 @@ const createStore = ({ nodes, edges, defaultNodes, defaultEdges, width, height,
         const nodeChanges = nodesToUnselect.map((n) => {
             const internalNode = nodeLookup.get(n.id);
             if (internalNode) {
-                // we need to unselect the internal node that was selected previously before we
-                // send the change to the user to prevent it to be selected while dragging the new node
+                /*
+                 * we need to unselect the internal node that was selected previously before we
+                 * send the change to the user to prevent it to be selected while dragging the new node
+                 */
                 internalNode.selected = false;
             }
             return createSelectionChange(n.id, false);
@@ -2926,8 +3251,10 @@ const createStore = ({ nodes, edges, defaultNodes, defaultEdges, width, height,
             maxZoom,
         }, options);
     },
-    // we can't call an asnychronous function in updateNodeInternals
-    // for that we created this sync version of fitView
+    /*
+     * we can't call an asnychronous function in updateNodeInternals
+     * for that we created this sync version of fitView
+     */
     fitViewSync: (options) => {
         const { panZoom, width, height, minZoom, maxZoom, nodeLookup } = get();
         if (!panZoom) {
@@ -2955,6 +3282,40 @@ const createStore = ({ nodes, edges, defaultNodes, defaultEdges, width, height,
     reset: () => set({ ...getInitialState() }),
 }), Object.is);
 
+/**
+ * The `<ReactFlowProvider />` component is a [context provider](https://react.dev/learn/passing-data-deeply-with-context#)
+ * that makes it possible to access a flow's internal state outside of the
+ * [`<ReactFlow />`](/api-reference/react-flow) component. Many of the hooks we
+ * provide rely on this component to work.
+ * @public
+ *
+ * @example
+ * ```tsx
+ *import { ReactFlow, ReactFlowProvider, useNodes } from '@xyflow/react'
+ *
+ *export default function Flow() {
+ *  return (
+ *    <ReactFlowProvider>
+ *      <ReactFlow nodes={...} edges={...} />
+ *      <Sidebar />
+ *    </ReactFlowProvider>
+ *  );
+ *}
+ *
+ *function Sidebar() {
+ *  // This hook will only work if the component it's used in is a child of a
+ *  // <ReactFlowProvider />.
+ *  const nodes = useNodes()
+ *
+ *  return <aside>do something with nodes</aside>;
+ *}
+ *```
+ *
+ * @remarks If you're using a router and want your flow's state to persist across routes,
+ * it's vital that you place the `<ReactFlowProvider />` component _outside_ of
+ * your router. If you have multiple flows on the same page you will need to use a separate
+ * `<ReactFlowProvider />` for each flow.
+ */
 function ReactFlowProvider({ initialNodes: nodes, initialEdges: edges, defaultNodes, defaultEdges, initialWidth: width, initialHeight: height, fitView, nodeOrigin, nodeExtent, children, }) {
     const [store] = useState(() => createStore({
         nodes,
@@ -2973,8 +3334,10 @@ function ReactFlowProvider({ initialNodes: nodes, initialEdges: edges, defaultNo
 function Wrapper({ children, nodes, edges, defaultNodes, defaultEdges, width, height, fitView, nodeOrigin, nodeExtent, }) {
     const isWrapped = useContext(StoreContext);
     if (isWrapped) {
-        // we need to wrap it with a fragment because it's not allowed for children to be a ReactNode
-        // https://github.com/DefinitelyTyped/DefinitelyTyped/issues/18051
+        /*
+         * we need to wrap it with a fragment because it's not allowed for children to be a ReactNode
+         * https://github.com/DefinitelyTyped/DefinitelyTyped/issues/18051
+         */
         return jsx(Fragment, { children: children });
     }
     return (jsx(ReactFlowProvider, { initialNodes: nodes, initialEdges: edges, defaultNodes: defaultNodes, defaultEdges: defaultEdges, initialWidth: width, initialHeight: height, fitView: fitView, nodeOrigin: nodeOrigin, nodeExtent: nodeExtent, children: children }));
@@ -2987,14 +3350,79 @@ const wrapperStyle = {
     position: 'relative',
     zIndex: 0,
 };
-function ReactFlow({ nodes, edges, defaultNodes, defaultEdges, className, nodeTypes, edgeTypes, onNodeClick, onEdgeClick, onInit, onMove, onMoveStart, onMoveEnd, onConnect, onConnectStart, onConnectEnd, onClickConnectStart, onClickConnectEnd, onNodeMouseEnter, onNodeMouseMove, onNodeMouseLeave, onNodeContextMenu, onNodeDoubleClick, onNodeDragStart, onNodeDrag, onNodeDragStop, onNodesDelete, onEdgesDelete, onDelete, onSelectionChange, onSelectionDragStart, onSelectionDrag, onSelectionDragStop, onSelectionContextMenu, onSelectionStart, onSelectionEnd, onBeforeDelete, connectionMode, connectionLineType = ConnectionLineType.Bezier, connectionLineStyle, connectionLineComponent, connectionLineContainerStyle, deleteKeyCode = 'Backspace', selectionKeyCode = 'Shift', selectionOnDrag = false, selectionMode = SelectionMode.Full, panActivationKeyCode = 'Space', multiSelectionKeyCode = isMacOs() ? 'Meta' : 'Control', zoomActivationKeyCode = isMacOs() ? 'Meta' : 'Control', snapToGrid, snapGrid, onlyRenderVisibleElements = false, selectNodesOnDrag, nodesDraggable, nodesConnectable, nodesFocusable, nodeOrigin = defaultNodeOrigin, edgesFocusable, edgesReconnectable, elementsSelectable = true, defaultViewport: defaultViewport$1 = defaultViewport, minZoom = 0.5, maxZoom = 2, translateExtent = infiniteExtent, preventScrolling = true, nodeExtent, defaultMarkerColor = '#b1b1b7', zoomOnScroll = true, zoomOnPinch = true, panOnScroll = false, panOnScrollSpeed = 0.5, panOnScrollMode = PanOnScrollMode.Free, zoomOnDoubleClick = true, panOnDrag = true, onPaneClick, onPaneMouseEnter, onPaneMouseMove, onPaneMouseLeave, onPaneScroll, onPaneContextMenu, paneClickDistance = 0, nodeClickDistance = 0, children, onReconnect, onReconnectStart, onReconnectEnd, onEdgeContextMenu, onEdgeDoubleClick, onEdgeMouseEnter, onEdgeMouseMove, onEdgeMouseLeave, reconnectRadius = 10, onNodesChange, onEdgesChange, noDragClassName = 'nodrag', noWheelClassName = 'nowheel', noPanClassName = 'nopan', fitView, fitViewOptions, connectOnClick, attributionPosition, proOptions, defaultEdgeOptions, elevateNodesOnSelect, elevateEdgesOnSelect, disableKeyboardA11y = false, autoPanOnConnect, autoPanOnNodeDrag, autoPanSpeed, connectionRadius, isValidConnection, onError, style, id, nodeDragThreshold, viewport, onViewportChange, width, height, colorMode = 'light', debug, ...rest }, ref) {
+function ReactFlow({ nodes, edges, defaultNodes, defaultEdges, className, nodeTypes, edgeTypes, onNodeClick, onEdgeClick, onInit, onMove, onMoveStart, onMoveEnd, onConnect, onConnectStart, onConnectEnd, onClickConnectStart, onClickConnectEnd, onNodeMouseEnter, onNodeMouseMove, onNodeMouseLeave, onNodeContextMenu, onNodeDoubleClick, onNodeDragStart, onNodeDrag, onNodeDragStop, onNodesDelete, onEdgesDelete, onDelete, onSelectionChange, onSelectionDragStart, onSelectionDrag, onSelectionDragStop, onSelectionContextMenu, onSelectionStart, onSelectionEnd, onBeforeDelete, connectionMode, connectionLineType = ConnectionLineType.Bezier, connectionLineStyle, connectionLineComponent, connectionLineContainerStyle, deleteKeyCode = 'Backspace', selectionKeyCode = 'Shift', selectionOnDrag = false, selectionMode = SelectionMode.Full, panActivationKeyCode = 'Space', multiSelectionKeyCode = isMacOs() ? 'Meta' : 'Control', zoomActivationKeyCode = isMacOs() ? 'Meta' : 'Control', snapToGrid, snapGrid, onlyRenderVisibleElements = false, selectNodesOnDrag, nodesDraggable, nodesConnectable, nodesFocusable, nodeOrigin = defaultNodeOrigin, edgesFocusable, edgesReconnectable, elementsSelectable = true, defaultViewport: defaultViewport$1 = defaultViewport, minZoom = 0.5, maxZoom = 2, translateExtent = infiniteExtent, preventScrolling = true, nodeExtent, defaultMarkerColor = '#b1b1b7', zoomOnScroll = true, zoomOnPinch = true, panOnScroll = false, panOnScrollSpeed = 0.5, panOnScrollMode = PanOnScrollMode.Free, zoomOnDoubleClick = true, panOnDrag = true, onPaneClick, onPaneMouseEnter, onPaneMouseMove, onPaneMouseLeave, onPaneScroll, onPaneContextMenu, paneClickDistance = 0, nodeClickDistance = 0, children, onReconnect, onReconnectStart, onReconnectEnd, onEdgeContextMenu, onEdgeDoubleClick, onEdgeMouseEnter, onEdgeMouseMove, onEdgeMouseLeave, reconnectRadius = 10, onNodesChange, onEdgesChange, noDragClassName = 'nodrag', noWheelClassName = 'nowheel', noPanClassName = 'nopan', fitView, fitViewOptions, connectOnClick, attributionPosition, proOptions, defaultEdgeOptions, elevateNodesOnSelect, elevateEdgesOnSelect, disableKeyboardA11y = false, autoPanOnConnect, autoPanOnNodeDrag, autoPanSpeed, connectionRadius, isValidConnection, onError, style, id, nodeDragThreshold, viewport, onViewportChange, width, height, colorMode = 'light', debug, onScroll, ...rest }, ref) {
     const rfId = id || '1';
     const colorModeClassName = useColorModeClass(colorMode);
-    return (jsx("div", { "data-testid": "rf__wrapper", ...rest, style: { ...style, ...wrapperStyle }, ref: ref, className: cc(['react-flow', className, colorModeClassName]), id: id, children: jsxs(Wrapper, { nodes: nodes, edges: edges, width: width, height: height, fitView: fitView, nodeOrigin: nodeOrigin, nodeExtent: nodeExtent, children: [jsx(GraphView, { onInit: onInit, onNodeClick: onNodeClick, onEdgeClick: onEdgeClick, onNodeMouseEnter: onNodeMouseEnter, onNodeMouseMove: onNodeMouseMove, onNodeMouseLeave: onNodeMouseLeave, onNodeContextMenu: onNodeContextMenu, onNodeDoubleClick: onNodeDoubleClick, nodeTypes: nodeTypes, edgeTypes: edgeTypes, connectionLineType: connectionLineType, connectionLineStyle: connectionLineStyle, connectionLineComponent: connectionLineComponent, connectionLineContainerStyle: connectionLineContainerStyle, selectionKeyCode: selectionKeyCode, selectionOnDrag: selectionOnDrag, selectionMode: selectionMode, deleteKeyCode: deleteKeyCode, multiSelectionKeyCode: multiSelectionKeyCode, panActivationKeyCode: panActivationKeyCode, zoomActivationKeyCode: zoomActivationKeyCode, onlyRenderVisibleElements: onlyRenderVisibleElements, defaultViewport: defaultViewport$1, translateExtent: translateExtent, minZoom: minZoom, maxZoom: maxZoom, preventScrolling: preventScrolling, zoomOnScroll: zoomOnScroll, zoomOnPinch: zoomOnPinch, zoomOnDoubleClick: zoomOnDoubleClick, panOnScroll: panOnScroll, panOnScrollSpeed: panOnScrollSpeed, panOnScrollMode: panOnScrollMode, panOnDrag: panOnDrag, onPaneClick: onPaneClick, onPaneMouseEnter: onPaneMouseEnter, onPaneMouseMove: onPaneMouseMove, onPaneMouseLeave: onPaneMouseLeave, onPaneScroll: onPaneScroll, onPaneContextMenu: onPaneContextMenu, paneClickDistance: paneClickDistance, nodeClickDistance: nodeClickDistance, onSelectionContextMenu: onSelectionContextMenu, onSelectionStart: onSelectionStart, onSelectionEnd: onSelectionEnd, onReconnect: onReconnect, onReconnectStart: onReconnectStart, onReconnectEnd: onReconnectEnd, onEdgeContextMenu: onEdgeContextMenu, onEdgeDoubleClick: onEdgeDoubleClick, onEdgeMouseEnter: onEdgeMouseEnter, onEdgeMouseMove: onEdgeMouseMove, onEdgeMouseLeave: onEdgeMouseLeave, reconnectRadius: reconnectRadius, defaultMarkerColor: defaultMarkerColor, noDragClassName: noDragClassName, noWheelClassName: noWheelClassName, noPanClassName: noPanClassName, rfId: rfId, disableKeyboardA11y: disableKeyboardA11y, nodeExtent: nodeExtent, viewport: viewport, onViewportChange: onViewportChange }), jsx(StoreUpdater, { nodes: nodes, edges: edges, defaultNodes: defaultNodes, defaultEdges: defaultEdges, onConnect: onConnect, onConnectStart: onConnectStart, onConnectEnd: onConnectEnd, onClickConnectStart: onClickConnectStart, onClickConnectEnd: onClickConnectEnd, nodesDraggable: nodesDraggable, nodesConnectable: nodesConnectable, nodesFocusable: nodesFocusable, edgesFocusable: edgesFocusable, edgesReconnectable: edgesReconnectable, elementsSelectable: elementsSelectable, elevateNodesOnSelect: elevateNodesOnSelect, elevateEdgesOnSelect: elevateEdgesOnSelect, minZoom: minZoom, maxZoom: maxZoom, nodeExtent: nodeExtent, onNodesChange: onNodesChange, onEdgesChange: onEdgesChange, snapToGrid: snapToGrid, snapGrid: snapGrid, connectionMode: connectionMode, translateExtent: translateExtent, connectOnClick: connectOnClick, defaultEdgeOptions: defaultEdgeOptions, fitView: fitView, fitViewOptions: fitViewOptions, onNodesDelete: onNodesDelete, onEdgesDelete: onEdgesDelete, onDelete: onDelete, onNodeDragStart: onNodeDragStart, onNodeDrag: onNodeDrag, onNodeDragStop: onNodeDragStop, onSelectionDrag: onSelectionDrag, onSelectionDragStart: onSelectionDragStart, onSelectionDragStop: onSelectionDragStop, onMove: onMove, onMoveStart: onMoveStart, onMoveEnd: onMoveEnd, noPanClassName: noPanClassName, nodeOrigin: nodeOrigin, rfId: rfId, autoPanOnConnect: autoPanOnConnect, autoPanOnNodeDrag: autoPanOnNodeDrag, autoPanSpeed: autoPanSpeed, onError: onError, connectionRadius: connectionRadius, isValidConnection: isValidConnection, selectNodesOnDrag: selectNodesOnDrag, nodeDragThreshold: nodeDragThreshold, onBeforeDelete: onBeforeDelete, paneClickDistance: paneClickDistance, debug: debug }), jsx(SelectionListener, { onSelectionChange: onSelectionChange }), children, jsx(Attribution, { proOptions: proOptions, position: attributionPosition }), jsx(A11yDescriptions, { rfId: rfId, disableKeyboardA11y: disableKeyboardA11y })] }) }));
+    // Undo scroll events, preventing viewport from shifting when nodes outside of it are focused
+    const wrapperOnScroll = useCallback((e) => {
+        e.currentTarget.scrollTo({ top: 0, left: 0, behavior: 'instant' });
+        onScroll?.(e);
+    }, [onScroll]);
+    return (jsx("div", { "data-testid": "rf__wrapper", ...rest, onScroll: wrapperOnScroll, style: { ...style, ...wrapperStyle }, ref: ref, className: cc(['react-flow', className, colorModeClassName]), id: id, children: jsxs(Wrapper, { nodes: nodes, edges: edges, width: width, height: height, fitView: fitView, nodeOrigin: nodeOrigin, nodeExtent: nodeExtent, children: [jsx(GraphView, { onInit: onInit, onNodeClick: onNodeClick, onEdgeClick: onEdgeClick, onNodeMouseEnter: onNodeMouseEnter, onNodeMouseMove: onNodeMouseMove, onNodeMouseLeave: onNodeMouseLeave, onNodeContextMenu: onNodeContextMenu, onNodeDoubleClick: onNodeDoubleClick, nodeTypes: nodeTypes, edgeTypes: edgeTypes, connectionLineType: connectionLineType, connectionLineStyle: connectionLineStyle, connectionLineComponent: connectionLineComponent, connectionLineContainerStyle: connectionLineContainerStyle, selectionKeyCode: selectionKeyCode, selectionOnDrag: selectionOnDrag, selectionMode: selectionMode, deleteKeyCode: deleteKeyCode, multiSelectionKeyCode: multiSelectionKeyCode, panActivationKeyCode: panActivationKeyCode, zoomActivationKeyCode: zoomActivationKeyCode, onlyRenderVisibleElements: onlyRenderVisibleElements, defaultViewport: defaultViewport$1, translateExtent: translateExtent, minZoom: minZoom, maxZoom: maxZoom, preventScrolling: preventScrolling, zoomOnScroll: zoomOnScroll, zoomOnPinch: zoomOnPinch, zoomOnDoubleClick: zoomOnDoubleClick, panOnScroll: panOnScroll, panOnScrollSpeed: panOnScrollSpeed, panOnScrollMode: panOnScrollMode, panOnDrag: panOnDrag, onPaneClick: onPaneClick, onPaneMouseEnter: onPaneMouseEnter, onPaneMouseMove: onPaneMouseMove, onPaneMouseLeave: onPaneMouseLeave, onPaneScroll: onPaneScroll, onPaneContextMenu: onPaneContextMenu, paneClickDistance: paneClickDistance, nodeClickDistance: nodeClickDistance, onSelectionContextMenu: onSelectionContextMenu, onSelectionStart: onSelectionStart, onSelectionEnd: onSelectionEnd, onReconnect: onReconnect, onReconnectStart: onReconnectStart, onReconnectEnd: onReconnectEnd, onEdgeContextMenu: onEdgeContextMenu, onEdgeDoubleClick: onEdgeDoubleClick, onEdgeMouseEnter: onEdgeMouseEnter, onEdgeMouseMove: onEdgeMouseMove, onEdgeMouseLeave: onEdgeMouseLeave, reconnectRadius: reconnectRadius, defaultMarkerColor: defaultMarkerColor, noDragClassName: noDragClassName, noWheelClassName: noWheelClassName, noPanClassName: noPanClassName, rfId: rfId, disableKeyboardA11y: disableKeyboardA11y, nodeExtent: nodeExtent, viewport: viewport, onViewportChange: onViewportChange }), jsx(StoreUpdater, { nodes: nodes, edges: edges, defaultNodes: defaultNodes, defaultEdges: defaultEdges, onConnect: onConnect, onConnectStart: onConnectStart, onConnectEnd: onConnectEnd, onClickConnectStart: onClickConnectStart, onClickConnectEnd: onClickConnectEnd, nodesDraggable: nodesDraggable, nodesConnectable: nodesConnectable, nodesFocusable: nodesFocusable, edgesFocusable: edgesFocusable, edgesReconnectable: edgesReconnectable, elementsSelectable: elementsSelectable, elevateNodesOnSelect: elevateNodesOnSelect, elevateEdgesOnSelect: elevateEdgesOnSelect, minZoom: minZoom, maxZoom: maxZoom, nodeExtent: nodeExtent, onNodesChange: onNodesChange, onEdgesChange: onEdgesChange, snapToGrid: snapToGrid, snapGrid: snapGrid, connectionMode: connectionMode, translateExtent: translateExtent, connectOnClick: connectOnClick, defaultEdgeOptions: defaultEdgeOptions, fitView: fitView, fitViewOptions: fitViewOptions, onNodesDelete: onNodesDelete, onEdgesDelete: onEdgesDelete, onDelete: onDelete, onNodeDragStart: onNodeDragStart, onNodeDrag: onNodeDrag, onNodeDragStop: onNodeDragStop, onSelectionDrag: onSelectionDrag, onSelectionDragStart: onSelectionDragStart, onSelectionDragStop: onSelectionDragStop, onMove: onMove, onMoveStart: onMoveStart, onMoveEnd: onMoveEnd, noPanClassName: noPanClassName, nodeOrigin: nodeOrigin, rfId: rfId, autoPanOnConnect: autoPanOnConnect, autoPanOnNodeDrag: autoPanOnNodeDrag, autoPanSpeed: autoPanSpeed, onError: onError, connectionRadius: connectionRadius, isValidConnection: isValidConnection, selectNodesOnDrag: selectNodesOnDrag, nodeDragThreshold: nodeDragThreshold, onBeforeDelete: onBeforeDelete, paneClickDistance: paneClickDistance, debug: debug }), jsx(SelectionListener, { onSelectionChange: onSelectionChange }), children, jsx(Attribution, { proOptions: proOptions, position: attributionPosition }), jsx(A11yDescriptions, { rfId: rfId, disableKeyboardA11y: disableKeyboardA11y })] }) }));
 }
+/**
+ * The `<ReactFlow />` component is the heart of your React Flow application.
+ * It renders your nodes and edges and handles user interaction
+ *
+ * @public
+ *
+ * @example
+ * ```tsx
+ *import { ReactFlow } from '@xyflow/react'
+ *
+ *export default function Flow() {
+ *  return (<ReactFlow
+ *    nodes={...}
+ *    edges={...}
+ *    onNodesChange={...}
+ *    ...
+ *  />);
+ *}
+ *```
+ */
 var index = fixedForwardRef(ReactFlow);
 
 const selector$6 = (s) => s.domNode?.querySelector('.react-flow__edgelabel-renderer');
+/**
+ * Edges are SVG-based. If you want to render more complex labels you can use the
+ * `<EdgeLabelRenderer />` component to access a div based renderer. This component
+ * is a portal that renders the label in a `<div />` that is positioned on top of
+ * the edges. You can see an example usage of the component in the [edge label renderer](/examples/edges/edge-label-renderer) example.
+ * @public
+ *
+ * @example
+ *```jsx
+ *import React from 'react';
+ *import { getBezierPath, EdgeLabelRenderer, BaseEdge } from '@xyflow/react';
+ *
+ *export function CustomEdge({ id, data, ...props }) {
+ *  const [edgePath, labelX, labelY] = getBezierPath(props);
+ *
+ *  return (
+ *    <>
+ *      <BaseEdge id={id} path={edgePath} />
+ *      <EdgeLabelRenderer>
+ *        <div
+ *          style={{
+ *            position: 'absolute',
+ *            transform: `translate(-50%, -50%) translate(${labelX}px,${labelY}px)`,
+ *            background: '#ffcc00',
+ *            padding: 10,
+ *        }}
+ *          className="nodrag nopan"
+ *        >
+ *         {data.label}
+ *        </div>
+ *      </EdgeLabelRenderer>
+ *    </>
+ *  );
+ *};
+ *```
+ *
+ * @remarks The `<EdgeLabelRenderer />` has no pointer events by default. If you want to
+ * add mouse interactions you need to set the style `pointerEvents: all` and add
+ * the `nopan` class on the label or the element you want to interact with.
+ */
 function EdgeLabelRenderer({ children }) {
     const edgeLabelRenderer = useStore(selector$6);
     if (!edgeLabelRenderer) {
@@ -3004,6 +3432,31 @@ function EdgeLabelRenderer({ children }) {
 }
 
 const selector$5 = (s) => s.domNode?.querySelector('.react-flow__viewport-portal');
+/**
+ * The `<ViewportPortal />` component can be used to add components to the same viewport
+ * of the flow where nodes and edges are rendered. This is useful when you want to render
+ * your own components that are adhere to the same coordinate system as the nodes & edges
+ * and are also affected by zooming and panning
+ * @public
+ * @example
+ *
+ * ```jsx
+ *import React from 'react';
+ *import { ViewportPortal } from '@xyflow/react';
+ *
+ *export default function () {
+ *  return (
+ *    <ViewportPortal>
+ *      <div
+ *        style={{ transform: 'translate(100px, 100px)', position: 'absolute' }}
+ *      >
+ *        This div is positioned at [100, 100] on the flow.
+ *      </div>
+ *    </ViewportPortal>
+ *  );
+ *}
+ *```
+ */
 function ViewportPortal({ children }) {
     const viewPortalDiv = useStore(selector$5);
     if (!viewPortalDiv) {
@@ -3013,10 +3466,48 @@ function ViewportPortal({ children }) {
 }
 
 /**
- * Hook for updating node internals.
+ * When you programmatically add or remove handles to a node or update a node's
+ *handle position, you need to let React Flow know about it using this hook. This
+ *will update the internal dimensions of the node and properly reposition handles
+ *on the canvas if necessary.
  *
  * @public
  * @returns function for updating node internals
+ *
+ * @example
+ * ```jsx
+ *import { useCallback, useState } from 'react';
+ *import { Handle, useUpdateNodeInternals } from '@xyflow/react';
+ *
+ *export default function RandomHandleNode({ id }) {
+ *  const updateNodeInternals = useUpdateNodeInternals();
+ *  const [handleCount, setHandleCount] = useState(0);
+ *  const randomizeHandleCount = useCallback(() => {
+ *   setHandleCount(Math.floor(Math.random() * 10));
+ *    updateNodeInternals(id);
+ *  }, [id, updateNodeInternals]);
+ *
+ *  return (
+ *    <>
+ *      {Array.from({ length: handleCount }).map((_, index) => (
+ *        <Handle
+ *          key={index}
+ *          type="target"
+ *          position="left"
+ *          id={`handle-${index}`}
+ *        />
+ *      ))}
+ *
+ *      <div>
+ *        <button onClick={randomizeHandleCount}>Randomize handle count</button>
+ *        <p>There are {handleCount} handles on this node.</p>
+ *      </div>
+ *    </>
+ *  );
+ *}
+ *```
+ * @remarks This hook can only be used in a component that is a child of a
+ *{@link ReactFlowProvider} or a {@link ReactFlow} component.
  */
 function useUpdateNodeInternals() {
     const store = useStoreApi();
@@ -3036,10 +3527,23 @@ function useUpdateNodeInternals() {
 
 const nodesSelector = (state) => state.nodes;
 /**
- * Hook for getting the current nodes from the store.
+ * This hook returns an array of the current nodes. Components that use this hook
+ * will re-render **whenever any node changes**, including when a node is selected
+ * or moved.
  *
  * @public
  * @returns An array of nodes
+ *
+ * @example
+ * ```jsx
+ *import { useNodes } from '@xyflow/react';
+ *
+ *export default function() {
+ *  const nodes = useNodes();
+ *
+ *  return <div>There are currently {nodes.length} nodes!</div>;
+ *}
+ *```
  */
 function useNodes() {
     const nodes = useStore(nodesSelector, shallow);
@@ -3048,10 +3552,22 @@ function useNodes() {
 
 const edgesSelector = (state) => state.edges;
 /**
- * Hook for getting the current edges from the store.
+ * This hook returns an array of the current edges. Components that use this hook
+ * will re-render **whenever any edge changes**.
  *
  * @public
  * @returns An array of edges
+ *
+ * @example
+ * ```tsx
+ *import { useEdges } from '@xyflow/react';
+ *
+ *export default function () {
+ *  const edges = useEdges();
+ *
+ *  return <div>There are currently {edges.length} edges!</div>;
+ *}
+ *```
  */
 function useEdges() {
     const edges = useStore(edgesSelector, shallow);
@@ -3064,10 +3580,33 @@ const viewportSelector = (state) => ({
     zoom: state.transform[2],
 });
 /**
- * Hook for getting the current viewport from the store.
+ * The `useViewport` hook is a convenient way to read the current state of the
+ *{@link Viewport} in a component. Components that use this hook
+ *will re-render **whenever the viewport changes**.
  *
  * @public
  * @returns The current viewport
+ *
+ * @example
+ *
+ *```jsx
+ *import { useViewport } from '@xyflow/react';
+ *
+ *export default function ViewportDisplay() {
+ *  const { x, y, zoom } = useViewport();
+ *
+ *  return (
+ *    <div>
+ *      <p>
+ *        The viewport is currently at ({x}, {y}) and zoomed to {zoom}.
+ *      </p>
+ *    </div>
+ *  );
+ *}
+ *```
+ *
+ * @remarks This hook can only be used in a component that is a child of a
+ *{@link ReactFlowProvider} or a {@link ReactFlow} component.
  */
 function useViewport() {
     const viewport = useStore(viewportSelector, shallow);
@@ -3075,11 +3614,41 @@ function useViewport() {
 }
 
 /**
- * Hook for managing the state of nodes - should only be used for prototyping / simple use cases.
+ * This hook makes it easy to prototype a controlled flow where you manage the
+ * state of nodes and edges outside the `ReactFlowInstance`. You can think of it
+ * like React's `useState` hook with an additional helper callback.
  *
  * @public
  * @param initialNodes
  * @returns an array [nodes, setNodes, onNodesChange]
+ * @example
+ *
+ *```tsx
+ *import { ReactFlow, useNodesState, useEdgesState } from '@xyflow/react';
+ *
+ *const initialNodes = [];
+ *const initialEdges = [];
+ *
+ *export default function () {
+ *  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
+ *  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);
+ *
+ *  return (
+ *    <ReactFlow
+ *      nodes={nodes}
+ *      edges={edges}
+ *      onNodesChange={onNodesChange}
+ *      onEdgesChange={onEdgesChange}
+ *    />
+ *  );
+ *}
+ *```
+ *
+ * @remarks This hook was created to make prototyping easier and our documentation
+ * examples clearer. Although it is OK to use this hook in production, in
+ * practice you may want to use a more sophisticated state management solution
+ * like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead.
+ *
  */
 function useNodesState(initialNodes) {
     const [nodes, setNodes] = useState(initialNodes);
@@ -3087,11 +3656,41 @@ function useNodesState(initialNodes) {
     return [nodes, setNodes, onNodesChange];
 }
 /**
- * Hook for managing the state of edges - should only be used for prototyping / simple use cases.
+ * This hook makes it easy to prototype a controlled flow where you manage the
+ * state of nodes and edges outside the `ReactFlowInstance`. You can think of it
+ * like React's `useState` hook with an additional helper callback.
  *
  * @public
  * @param initialEdges
  * @returns an array [edges, setEdges, onEdgesChange]
+ * @example
+ *
+ *```tsx
+ *import { ReactFlow, useNodesState, useEdgesState } from '@xyflow/react';
+ *
+ *const initialNodes = [];
+ *const initialEdges = [];
+ *
+ *export default function () {
+ *  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
+ *  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);
+ *
+ *  return (
+ *    <ReactFlow
+ *      nodes={nodes}
+ *      edges={edges}
+ *      onNodesChange={onNodesChange}
+ *      onEdgesChange={onEdgesChange}
+ *    />
+ *  );
+ *}
+ *```
+ *
+ * @remarks This hook was created to make prototyping easier and our documentation
+ * examples clearer. Although it is OK to use this hook in production, in
+ * practice you may want to use a more sophisticated state management solution
+ * like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead.
+ *
  */
 function useEdgesState(initialEdges) {
     const [edges, setEdges] = useState(initialEdges);
@@ -3100,12 +3699,30 @@ function useEdgesState(initialEdges) {
 }
 
 /**
- * Hook for registering an onViewportChange handler.
+ * The `useOnViewportChange` hook lets you listen for changes to the viewport such
+ *as panning and zooming. You can provide a callback for each phase of a viewport
+ *change: `onStart`, `onChange`, and `onEnd`.
  *
  * @public
  * @param params.onStart - gets called when the viewport starts changing
  * @param params.onChange - gets called when the viewport changes
  * @param params.onEnd - gets called when the viewport stops changing
+ *
+ * @example
+ * ```jsx
+ *import { useCallback } from 'react';
+ *import { useOnViewportChange } from '@xyflow/react';
+ *
+ *function ViewportChangeLogger() {
+ *  useOnViewportChange({
+ *    onStart: (viewport: Viewport) => console.log('start', viewport),
+ *    onChange: (viewport: Viewport) => console.log('change', viewport),
+ *    onEnd: (viewport: Viewport) => console.log('end', viewport),
+ *  });
+ *
+ *  return null;
+ *}
+ *```
  */
 function useOnViewportChange({ onStart, onChange, onEnd }) {
     const store = useStoreApi();
@@ -3121,10 +3738,42 @@ function useOnViewportChange({ onStart, onChange, onEnd }) {
 }
 
 /**
- * Hook for registering an onSelectionChange handler.
+ * This hook lets you listen for changes to both node and edge selection. As the
+ *name implies, the callback you provide will be called whenever the selection of
+ *_either_ nodes or edges changes.
  *
  * @public
  * @param params.onChange - The handler to register
+ *
+ * @example
+ * ```jsx
+ *import { useState } from 'react';
+ *import { ReactFlow, useOnSelectionChange } from '@xyflow/react';
+ *
+ *function SelectionDisplay() {
+ *  const [selectedNodes, setSelectedNodes] = useState([]);
+ *  const [selectedEdges, setSelectedEdges] = useState([]);
+ *
+ *  // the passed handler has to be memoized, otherwise the hook will not work correctly
+ *  const onChange = useCallback(({ nodes, edges }) => {
+ *    setSelectedNodes(nodes.map((node) => node.id));
+ *    setSelectedEdges(edges.map((edge) => edge.id));
+ *  }, []);
+ *
+ *  useOnSelectionChange({
+ *    onChange,
+ *  });
+ *
+ *  return (
+ *    <div>
+ *      <p>Selected nodes: {selectedNodes.join(', ')}</p>
+ *      <p>Selected edges: {selectedEdges.join(', ')}</p>
+ *    </div>
+ *  );
+ *}
+ *```
+ *
+ * @remarks You need to memoize the passed `onChange` handler, otherwise the hook will not work correctly.
  */
 function useOnSelectionChange({ onChange }) {
     const store = useStoreApi();
@@ -3151,17 +3800,42 @@ const selector$4 = (options) => (s) => {
     }
     return true;
 };
-const defaultOptions = {
-    includeHiddenNodes: false,
-};
 /**
- * Hook which returns true when all nodes are initialized.
+ * This hook tells you whether all the nodes in a flow have been measured and given
+ *a width and height. When you add a node to the flow, this hook will return
+ *`false` and then `true` again once the node has been measured.
  *
  * @public
  * @param options.includeHiddenNodes - defaults to false
  * @returns boolean indicating whether all nodes are initialized
+ *
+ * @example
+ * ```jsx
+ *import { useReactFlow, useNodesInitialized } from '@xyflow/react';
+ *import { useEffect, useState } from 'react';
+ *
+ *const options = {
+ *  includeHiddenNodes: false,
+ *};
+ *
+ *export default function useLayout() {
+ *  const { getNodes } = useReactFlow();
+ *  const nodesInitialized = useNodesInitialized(options);
+ *  const [layoutedNodes, setLayoutedNodes] = useState(getNodes());
+ *
+ *  useEffect(() => {
+ *    if (nodesInitialized) {
+ *      setLayoutedNodes(yourLayoutingFunction(getNodes()));
+ *    }
+ *  }, [nodesInitialized]);
+ *
+ *  return layoutedNodes;
+ *}
+ *```
  */
-function useNodesInitialized(options = defaultOptions) {
+function useNodesInitialized(options = {
+    includeHiddenNodes: false,
+}) {
     const initialized = useStore(selector$4(options));
     return initialized;
 }
@@ -3198,7 +3872,7 @@ function useHandleConnections({ type, id, nodeId, onConnect, onDisconnect, }) {
 
 const error014 = errorMessages['error014']();
 /**
- * Hook to retrieve all edges connected to a node. Can be filtered by handle type and id.
+ * This hook returns an array of connections on a specific node, handle type ('source', 'target') or handle ID.
  *
  * @public
  * @param param.id - node id - optional if called inside a custom node
@@ -3207,6 +3881,22 @@ const error014 = errorMessages['error014']();
  * @param param.onConnect - gets called when a connection is established
  * @param param.onDisconnect - gets called when a connection is removed
  * @returns an array with connections
+ *
+ * @example
+ * ```jsx
+ *import { useNodeConnections } from '@xyflow/react';
+ *
+ *export default function () {
+ *  const connections = useNodeConnections({
+ *    type: 'target',
+ *    handleId: 'my-handle',
+ *  });
+ *
+ *  return (
+ *    <div>There are currently {connections.length} incoming connections!</div>
+ *  );
+ *}
+ *```
  */
 function useNodeConnections({ id, handleType, handleId, onConnect, onDisconnect, } = {}) {
     const nodeId = useNodeId();
@@ -3250,11 +3940,31 @@ function useNodesData(nodeIds) {
 }
 
 /**
- * Hook for getting an internal node by id
+ * This hook returns the internal representation of a specific node.
+ * Components that use this hook will re-render **whenever the node changes**,
+ * including when a node is selected or moved.
  *
  * @public
  * @param id - id of the node
  * @returns array with visible node ids
+ *
+ * @example
+ * ```tsx
+ *import { useInternalNode } from '@xyflow/react';
+ *
+ *export default function () {
+ *  const internalNode = useInternalNode('node-1');
+ *  const absolutePosition = internalNode.internals.positionAbsolute;
+ *
+ *  return (
+ *    <div>
+ *      The absolute position of the node is at:
+ *      <p>x: {absolutePosition.x}</p>
+ *      <p>y: {absolutePosition.y}</p>
+ *    </div>
+ *  );
+ *}
+ *```
  */
 function useInternalNode(id) {
     const node = useStore(useCallback((s) => s.nodeLookup.get(id), [id]), shallow);
@@ -3268,6 +3978,12 @@ function DotPattern({ radius, className }) {
     return (jsx("circle", { cx: radius, cy: radius, r: radius, className: cc(['react-flow__background-pattern', 'dots', className]) }));
 }
 
+/**
+ * The three variants are exported as an enum for convenience. You can either import
+ * the enum and use it like `BackgroundVariant.Lines` or you can use the raw string
+ * value directly.
+ * @public
+ */
 var BackgroundVariant;
 (function (BackgroundVariant) {
     BackgroundVariant["Lines"] = "lines";
@@ -3309,6 +4025,59 @@ size, lineWidth = 1, offset = 0, color, bgColor, style, className, patternClassN
         }, ref: ref, "data-testid": "rf__background", children: [jsx("pattern", { id: _patternId, x: transform[0] % scaledGap[0], y: transform[1] % scaledGap[1], width: scaledGap[0], height: scaledGap[1], patternUnits: "userSpaceOnUse", patternTransform: `translate(-${scaledOffset[0]},-${scaledOffset[1]})`, children: isDots ? (jsx(DotPattern, { radius: scaledSize / 2, className: patternClassName })) : (jsx(LinePattern, { dimensions: patternDimensions, lineWidth: lineWidth, variant: variant, className: patternClassName })) }), jsx("rect", { x: "0", y: "0", width: "100%", height: "100%", fill: `url(#${_patternId})` })] }));
 }
 BackgroundComponent.displayName = 'Background';
+/**
+ * The `<Background />` component makes it convenient to render different types of backgrounds common in node-based UIs. It comes with three variants: lines, dots and cross.
+ *
+ * @example
+ *
+ * A simple example of how to use the Background component.
+ *
+ * ```tsx
+ * import { useState } from 'react';
+ * import { ReactFlow, Background, BackgroundVariant } from '@xyflow/react';
+ *
+ * export default function Flow() {
+ *   return (
+ *     <ReactFlow defaultNodes={[...]} defaultEdges={[...]}>
+ *       <Background color="#ccc" variant={BackgroundVariant.Dots} />
+ *     </ReactFlow>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ *
+ * In this example you can see how to combine multiple backgrounds
+ *
+ * ```tsx
+ * import { ReactFlow, Background, BackgroundVariant } from '@xyflow/react';
+ * import '@xyflow/react/dist/style.css';
+ *
+ * export default function Flow() {
+ *   return (
+ *     <ReactFlow defaultNodes={[...]} defaultEdges={[...]}>
+ *       <Background
+ *         id="1"
+ *         gap={10}
+ *         color="#f1f1f1"
+ *         variant={BackgroundVariant.Lines}
+ *       />
+ *       <Background
+ *         id="2"
+ *         gap={100}
+ *         color="#ccc"
+ *         variant={BackgroundVariant.Lines}
+ *       />
+ *     </ReactFlow>
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ *
+ * When combining multiple <Background /> components it’s important to give each of them a unique id prop!
+ *
+ */
 const Background = memo(BackgroundComponent);
 
 function PlusIcon() {
@@ -3331,6 +4100,29 @@ function UnlockIcon() {
     return (jsx("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 25 32", children: jsx("path", { d: "M21.333 10.667H19.81V7.619C19.81 3.429 16.38 0 12.19 0c-4.114 1.828-1.37 2.133.305 2.438 1.676.305 4.42 2.59 4.42 5.181v3.048H3.047A3.056 3.056 0 000 13.714v15.238A3.056 3.056 0 003.048 32h18.285a3.056 3.056 0 003.048-3.048V13.714a3.056 3.056 0 00-3.048-3.047zM12.19 24.533a3.056 3.056 0 01-3.047-3.047 3.056 3.056 0 013.047-3.048 3.056 3.056 0 013.048 3.048 3.056 3.056 0 01-3.048 3.047z" }) }));
 }
 
+/**
+ * You can add buttons to the control panel by using the `<ControlButton />` component
+ * and pass it as a child to the [`<Controls />`](/api-reference/components/controls) component.
+ *
+ * @public
+ * @example
+ *```jsx
+ *import { MagicWand } from '@radix-ui/react-icons'
+ *import { ReactFlow, Controls, ControlButton } from '@xyflow/react'
+ *
+ *export default function Flow() {
+ *  return (
+ *    <ReactFlow nodes={[...]} edges={[...]}>
+ *      <Controls>
+ *        <ControlButton onClick={() => alert('Something magical just happened. ✨')}>
+ *          <MagicWand />
+ *        </ControlButton>
+ *      </Controls>
+ *    </ReactFlow>
+ *  )
+ *}
+ *```
+ */
 function ControlButton({ children, className, ...rest }) {
     return (jsx("button", { type: "button", className: cc(['react-flow__controls-button', className]), ...rest, children: children }));
 }
@@ -3368,6 +4160,27 @@ function ControlsComponent({ style, showZoom = true, showFitView = true, showInt
     return (jsxs(Panel, { className: cc(['react-flow__controls', orientationClass, className]), position: position, style: style, "data-testid": "rf__controls", "aria-label": ariaLabel, children: [showZoom && (jsxs(Fragment, { children: [jsx(ControlButton, { onClick: onZoomInHandler, className: "react-flow__controls-zoomin", title: "zoom in", "aria-label": "zoom in", disabled: maxZoomReached, children: jsx(PlusIcon, {}) }), jsx(ControlButton, { onClick: onZoomOutHandler, className: "react-flow__controls-zoomout", title: "zoom out", "aria-label": "zoom out", disabled: minZoomReached, children: jsx(MinusIcon, {}) })] })), showFitView && (jsx(ControlButton, { className: "react-flow__controls-fitview", onClick: onFitViewHandler, title: "fit view", "aria-label": "fit view", children: jsx(FitViewIcon, {}) })), showInteractive && (jsx(ControlButton, { className: "react-flow__controls-interactive", onClick: onToggleInteractivity, title: "toggle interactivity", "aria-label": "toggle interactivity", children: isInteractive ? jsx(UnlockIcon, {}) : jsx(LockIcon, {}) })), children] }));
 }
 ControlsComponent.displayName = 'Controls';
+/**
+ * The `<Controls />` component renders a small panel that contains convenient
+ * buttons to zoom in, zoom out, fit the view, and lock the viewport.
+ *
+ * @public
+ * @example
+ *```tsx
+ *import { ReactFlow, Controls } from '@xyflow/react'
+ *
+ *export default function Flow() {
+ *  return (
+ *    <ReactFlow nodes={[...]} edges={[...]}>
+ *      <Controls />
+ *    </ReactFlow>
+ *  )
+ *}
+ *```
+ *
+ * @remarks To extend or customise the controls, you can use the [`<ControlButton />`](/api-reference/components/control-button) component
+ *
+ */
 const Controls = memo(ControlsComponent);
 
 function MiniMapNodeComponent({ id, x, y, width, height, style, color, strokeColor, strokeWidth, className, borderRadius, shapeRendering, selected, onClick, }) {
@@ -3384,8 +4197,10 @@ const MiniMapNode = memo(MiniMapNodeComponent);
 const selectorNodeIds = (s) => s.nodes.map((node) => node.id);
 const getAttrFunction = (func) => func instanceof Function ? func : () => func;
 function MiniMapNodes({ nodeStrokeColor, nodeColor, nodeClassName = '', nodeBorderRadius = 5, nodeStrokeWidth, 
-// We need to rename the prop to be `CapitalCase` so that JSX will render it as
-// a component properly.
+/*
+ * We need to rename the prop to be `CapitalCase` so that JSX will render it as
+ * a component properly.
+ */
 nodeComponent: NodeComponent = MiniMapNode, onClick, }) {
     const nodeIds = useStore(selectorNodeIds, shallow);
     const nodeColorFunc = getAttrFunction(nodeColor);
@@ -3393,11 +4208,13 @@ nodeComponent: NodeComponent = MiniMapNode, onClick, }) {
     const nodeClassNameFunc = getAttrFunction(nodeClassName);
     const shapeRendering = typeof window === 'undefined' || !!window.chrome ? 'crispEdges' : 'geometricPrecision';
     return (jsx(Fragment, { children: nodeIds.map((nodeId) => (
-        // The split of responsibilities between MiniMapNodes and
-        // NodeComponentWrapper may appear weird. However, it’s designed to
-        // minimize the cost of updates when individual nodes change.
-        //
-        // For more details, see a similar commit in `NodeRenderer/index.tsx`.
+        /*
+         * The split of responsibilities between MiniMapNodes and
+         * NodeComponentWrapper may appear weird. However, it’s designed to
+         * minimize the cost of updates when individual nodes change.
+         *
+         * For more details, see a similar commit in `NodeRenderer/index.tsx`.
+         */
         jsx(NodeComponentWrapper, { id: nodeId, nodeColorFunc: nodeColorFunc, nodeStrokeColorFunc: nodeStrokeColorFunc, nodeClassNameFunc: nodeClassNameFunc, nodeBorderRadius: nodeBorderRadius, nodeStrokeWidth: nodeStrokeWidth, NodeComponent: NodeComponent, onClick: onClick, shapeRendering: shapeRendering }, nodeId))) }));
 }
 function NodeComponentWrapperInner({ id, nodeColorFunc, nodeStrokeColorFunc, nodeClassNameFunc, nodeBorderRadius, nodeStrokeWidth, shapeRendering, NodeComponent, onClick, }) {
@@ -3442,8 +4259,10 @@ const selector$1 = (s) => {
 };
 const ARIA_LABEL_KEY = 'react-flow__minimap-desc';
 function MiniMapComponent({ style, className, nodeStrokeColor, nodeColor, nodeClassName = '', nodeBorderRadius = 5, nodeStrokeWidth, 
-// We need to rename the prop to be `CapitalCase` so that JSX will render it as
-// a component properly.
+/*
+ * We need to rename the prop to be `CapitalCase` so that JSX will render it as
+ * a component properly.
+ */
 nodeComponent, bgColor, maskColor, maskStrokeColor, maskStrokeWidth, position = 'bottom-right', onClick, onNodeClick, pannable = false, zoomable = false, ariaLabel = 'React Flow mini map', inversePan, zoomStep = 10, offsetScale = 5, }) {
     const store = useStoreApi();
     const svg = useRef(null);
@@ -3513,6 +4332,26 @@ nodeComponent, bgColor, maskColor, maskStrokeColor, maskStrokeWidth, position =
         M${viewBB.x},${viewBB.y}h${viewBB.width}v${viewBB.height}h${-viewBB.width}z`, fillRule: "evenodd", pointerEvents: "none" })] }) }));
 }
 MiniMapComponent.displayName = 'MiniMap';
+/**
+ * The `<MiniMap />` component can be used to render an overview of your flow. It
+ * renders each node as an SVG element and visualizes where the current viewport is
+ * in relation to the rest of the flow.
+ *
+ * @public
+ * @example
+ *
+ * ```jsx
+ *import { ReactFlow, MiniMap } from '@xyflow/react';
+ *
+ *export default function Flow() {
+ *  return (
+ *    <ReactFlow nodes={[...]]} edges={[...]]}>
+ *      <MiniMap nodeStrokeWidth={3} />
+ *    </ReactFlow>
+ *  );
+ *}
+ *```
+ */
 const MiniMap = memo(MiniMapComponent);
 
 function ResizeControl({ nodeId, position, variant = ResizeControlVariant.Handle, className, style = {}, children, color, minWidth = 10, minHeight = 10, maxWidth = Number.MAX_VALUE, maxHeight = Number.MAX_VALUE, keepAspectRatio = false, shouldResize, onResizeStart, onResize, onResizeEnd, }) {
@@ -3565,8 +4404,10 @@ function ResizeControl({ nodeId, position, variant = ResizeControlVariant.Handle
                         };
                         const parentExpandChanges = handleExpandParent([child], nodeLookup, parentLookup, nodeOrigin);
                         changes.push(...parentExpandChanges);
-                        // when the parent was expanded by the child node, its position will be clamped at
-                        // 0,0 when node origin is 0,0 and to width, height if it's 1,1
+                        /*
+                         * when the parent was expanded by the child node, its position will be clamped at
+                         * 0,0 when node origin is 0,0 and to width, height if it's 1,1
+                         */
                         nextPosition.x = change.x ? Math.max(origin[0] * width, change.x) : undefined;
                         nextPosition.y = change.y ? Math.max(origin[1] * height, change.y) : undefined;
                     }
@@ -3644,8 +4485,37 @@ function ResizeControl({ nodeId, position, variant = ResizeControlVariant.Handle
     const controlStyle = color ? { ...style, [colorStyleProp]: color } : style;
     return (jsx("div", { className: cc(['react-flow__resize-control', 'nodrag', ...positionClassNames, variant, className]), ref: resizeControlRef, style: controlStyle, children: children }));
 }
+/**
+ * To create your own resizing UI, you can use the `NodeResizeControl` component where you can pass children (such as icons).
+ * @public
+ *
+ */
 const NodeResizeControl = memo(ResizeControl);
 
+/**
+ * The `<NodeResizer />` component can be used to add a resize functionality to your
+ * nodes. It renders draggable controls around the node to resize in all directions.
+ * @public
+ *
+ * @example
+ *```jsx
+ *import { memo } from 'react';
+ *import { Handle, Position, NodeResizer } from '@xyflow/react';
+ *
+ *function ResizableNode({ data }) {
+ *  return (
+ *    <>
+ *      <NodeResizer minWidth={100} minHeight={30} />
+ *      <Handle type="target" position={Position.Left} />
+ *      <div style={{ padding: 10 }}>{data.label}</div>
+ *      <Handle type="source" position={Position.Right} />
+ *    </>
+ *  );
+ *};
+ *
+ *export default memo(ResizableNode);
+ *```
+ */
 function NodeResizer({ nodeId, isVisible = true, handleClassName, handleStyle, lineClassName, lineStyle, color, minWidth = 10, minHeight = 10, maxWidth = Number.MAX_VALUE, maxHeight = Number.MAX_VALUE, keepAspectRatio = false, shouldResize, onResizeStart, onResize, onResizeEnd, }) {
     if (!isVisible) {
         return null;
@@ -3685,6 +4555,41 @@ const storeSelector = (state) => ({
     zoom: state.transform[2],
     selectedNodesCount: state.nodes.filter((node) => node.selected).length,
 });
+/**
+ * This component can render a toolbar or tooltip to one side of a custom node. This
+ * toolbar doesn't scale with the viewport so that the content is always visible.
+ *
+ * @public
+ * @example
+ * ```jsx
+ *import { memo } from 'react';
+ *import { Handle, Position, NodeToolbar } from '@xyflow/react';
+ *
+ *function CustomNode({ data }) {
+ *  return (
+ *    <>
+ *      <NodeToolbar isVisible={data.toolbarVisible} position={data.toolbarPosition}>
+ *        <button>delete</button>
+ *        <button>copy</button>
+ *        <button>expand</button>
+ *      </NodeToolbar>
+ *
+ *      <div style={{ padding: '10px 20px' }}>
+ *        {data.label}
+ *      </div>
+ *
+ *      <Handle type="target" position={Position.Left} />
+ *      <Handle type="source" position={Position.Right} />
+ *    </>
+ *  );
+ *};
+ *
+ *export default memo(CustomNode);
+ *```
+ * @remarks By default, the toolbar is only visible when a node is selected. If multiple
+ * nodes are selected it will not be visible to prevent overlapping toolbars or
+ * clutter. You can override this behavior by setting the `isVisible` prop to `true`.
+ */
 function NodeToolbar({ nodeId, children, className, style, isVisible, position = Position.Top, offset = 10, align = 'center', ...rest }) {
     const contextNodeId = useNodeId();
     const nodesSelector = useCallback((state) => {
@@ -3703,7 +4608,7 @@ function NodeToolbar({ nodeId, children, className, style, isVisible, position =
     // if isVisible is not set, we show the toolbar only if its node is selected and no other node is selected
     const isActive = typeof isVisible === 'boolean'
         ? isVisible
-        : nodes.size === 1 && nodes.values().next().value.selected && selectedNodesCount === 1;
+        : nodes.size === 1 && nodes.values().next().value?.selected && selectedNodesCount === 1;
     if (!isActive || !nodes.size) {
         return null;
     }