diff --git a/.changeset/five-students-divide.md b/.changeset/five-students-divide.md
new file mode 100644
index 00000000..b4e9e528
--- /dev/null
+++ b/.changeset/five-students-divide.md
@@ -0,0 +1,5 @@
+---
+'@xyflow/react': patch
+---
+
+Improve TSDoc comments for `useConnection` hook
diff --git a/packages/react/src/hooks/useConnection.ts b/packages/react/src/hooks/useConnection.ts
index 9ed14b67..7c748003 100644
--- a/packages/react/src/hooks/useConnection.ts
+++ b/packages/react/src/hooks/useConnection.ts
@@ -30,6 +30,10 @@ function getSelector<NodeType extends Node = Node, SelectorReturn = ConnectionSt
  * based on a certain condition (e.g. if the connection is valid or not).
  *
  * @public
+ * @param connectionSelector - An optional selector function used to extract a slice of the
+ * `ConnectionState` data. Using a selector can prevent component re-renders where data you don't
+ * otherwise care about might change. If a selector is not provided, the entire `ConnectionState`
+ * object is returned unchanged.
  * @example
  *
  * ```tsx