From f33ecc2cf6548d241cc9d44ec507b3d1b6848876 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 21 Oct 2025 18:01:34 +0000
Subject: [PATCH] Add documentation for useMatchRoute and useNavigate hooks

Co-authored-by: tannerlinsley <tannerlinsley@gmail.com>
---
 packages/react-router/src/Matches.tsx     | 21 +++++++++++++++++++++
 packages/react-router/src/useNavigate.tsx | 14 ++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/packages/react-router/src/Matches.tsx b/packages/react-router/src/Matches.tsx
index 0d1855de783..0d64831d944 100644
--- a/packages/react-router/src/Matches.tsx
+++ b/packages/react-router/src/Matches.tsx
@@ -123,6 +123,18 @@ export type UseMatchRouteOptions<
   MaskOptions<TRouter, TMaskFrom, TMaskTo> &
   MatchRouteOptions
 
+/**
+ * Create a matcher function for testing locations against route definitions.
+ *
+ * The returned function accepts standard navigation options (`to`, `params`,
+ * `search`, etc.) and returns either `false` (no match) or the matched params
+ * object when the route matches the current or pending location.
+ *
+ * Useful for conditional rendering and active UI states.
+ *
+ * @returns A `matchRoute(options)` function that returns `false` or params.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useMatchRouteHook
+ */
 export function useMatchRoute<TRouter extends AnyRouter = RegisteredRouter>() {
   const router = useRouter()
 
@@ -231,6 +243,15 @@ export function useMatches<
   } as any) as UseMatchesResult<TRouter, TSelected>
 }
 
+/**
+ * Read the full array of active route matches or select a derived subset.
+ *
+ * Useful for debugging, breadcrumbs, or aggregating metadata across matches.
+ *
+ * @returns The array of matches (or the selected value).
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useMatchesHook
+ */
+
 /**
  * Read the full array of active route matches or select a derived subset.
  *
diff --git a/packages/react-router/src/useNavigate.tsx b/packages/react-router/src/useNavigate.tsx
index 467c689c2c8..20b5cdec54a 100644
--- a/packages/react-router/src/useNavigate.tsx
+++ b/packages/react-router/src/useNavigate.tsx
@@ -7,6 +7,20 @@ import type {
   RegisteredRouter,
   UseNavigateResult,
 } from '@tanstack/router-core'
+/**
+ * Imperative navigation hook.
+ *
+ * Returns a stable `navigate(options)` function to change the current location
+ * programmatically. Prefer the `Link` component for user-initiated navigation,
+ * and use this hook from effects, callbacks, or handlers where imperative
+ * navigation is required.
+ *
+ * Options:
+ * - `from`: Optional route base used to resolve relative `to` paths.
+ *
+ * @returns A function that accepts `NavigateOptions`.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useNavigateHook
+ */
 export function useNavigate<
   TRouter extends AnyRouter = RegisteredRouter,
   TDefaultFrom extends string = string,