diff --git a/.changeset/selfish-nails-sing.md b/.changeset/selfish-nails-sing.md
new file mode 100644
index 00000000..d2119c6b
--- /dev/null
+++ b/.changeset/selfish-nails-sing.md
@@ -0,0 +1,5 @@
+---
+'@xyflow/react': patch
+---
+
+Add `experimental_useOnNodesChangeMiddleware` hook
diff --git a/packages/react/src/hooks/useOnEdgesChangeMiddleware.ts b/packages/react/src/hooks/useOnEdgesChangeMiddleware.ts
index 237b5280..d79d6773 100644
--- a/packages/react/src/hooks/useOnEdgesChangeMiddleware.ts
+++ b/packages/react/src/hooks/useOnEdgesChangeMiddleware.ts
@@ -4,6 +4,12 @@ import type { EdgeChange } from '@xyflow/system';
 import { useStoreApi } from './useStore';
 import type { Edge, Node } from '../types';
 
+/**
+ * Registers a middleware function to transform edge changes.
+ *
+ * @public
+ * @param fn - Middleware function. Should be memoized with useCallback to avoid re-registration.
+ */
 export function experimental_useOnEdgesChangeMiddleware<EdgeType extends Edge = Edge>(
   fn: (changes: EdgeChange<EdgeType>[]) => EdgeChange<EdgeType>[]
 ) {
diff --git a/packages/react/src/hooks/useOnNodesChangeMiddleware.ts b/packages/react/src/hooks/useOnNodesChangeMiddleware.ts
index cf9231f8..fe7ea6f6 100644
--- a/packages/react/src/hooks/useOnNodesChangeMiddleware.ts
+++ b/packages/react/src/hooks/useOnNodesChangeMiddleware.ts
@@ -4,6 +4,12 @@ import type { NodeChange } from '@xyflow/system';
 import { useStoreApi } from './useStore';
 import type { Edge, Node } from '../types';
 
+/**
+ * Registers a middleware function to transform node changes.
+ *
+ * @public
+ * @param fn - Middleware function. Should be memoized with useCallback to avoid re-registration.
+ */
 export function experimental_useOnNodesChangeMiddleware<NodeType extends Node = Node>(
   fn: (changes: NodeChange<NodeType>[]) => NodeChange<NodeType>[]
 ) {