From 309db13f2782f9063e0983b40692c9001877892a Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Mon, 20 Oct 2025 19:49:23 +0000
Subject: [PATCH] Add documentation for createLink, Link, useNavigate, and
 Navigate

Co-authored-by: tannerlinsley <tannerlinsley@gmail.com>
---
 packages/react-router/src/link.tsx        | 28 +++++++++++++++++++++++
 packages/react-router/src/useNavigate.tsx | 19 +++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/packages/react-router/src/link.tsx b/packages/react-router/src/link.tsx
index 2d4c2a60daf..92ee2d82426 100644
--- a/packages/react-router/src/link.tsx
+++ b/packages/react-router/src/link.tsx
@@ -514,6 +514,18 @@ export interface LinkComponentRoute<
   ): React.ReactElement
 }
 
+/**
+ * Creates a typed Link-like component that preserves TanStack Router's
+ * navigation semantics and type-safety while delegating rendering to the
+ * provided host component.
+ *
+ * Useful for integrating design system anchors/buttons while keeping
+ * router-aware props (eg. `to`, `params`, `search`, `preload`).
+ *
+ * @param Comp The host component to render (eg. a design-system Link/Button)
+ * @returns A router-aware component with the same API as `Link`.
+ * @link https://tanstack.com/router/latest/docs/framework/react/guide/custom-link
+ */
 export function createLink<const TComp>(
   Comp: Constrain<TComp, any, (props: CreateLinkProps) => ReactNode>,
 ): LinkComponent<TComp> {
@@ -522,6 +534,22 @@ export function createLink<const TComp>(
   }) as any
 }
 
+/**
+ * A strongly-typed anchor component for declarative navigation.
+ * Handles path, search, hash and state updates with optional route preloading
+ * and active-state styling.
+ *
+ * Non-obvious props include:
+ * - `preload`: Controls route preloading (eg. 'intent', 'render', 'viewport', true/false)
+ * - `preloadDelay`: Delay in ms before preloading on hover
+ * - `activeProps`/`inactiveProps`: Additional props merged when link is active/inactive
+ * - `resetScroll`/`hashScrollIntoView`: Control scroll behavior on navigation
+ * - `viewTransition`/`startTransition`: Use View Transitions/React transitions for navigation
+ * - `ignoreBlocker`: Bypass registered blockers
+ *
+ * @returns An anchor-like element that navigates without full page reloads.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/linkComponent
+ */
 export const Link: LinkComponent<'a'> = React.forwardRef<Element, any>(
   (props, ref) => {
     const { _asChild, ...rest } = props
diff --git a/packages/react-router/src/useNavigate.tsx b/packages/react-router/src/useNavigate.tsx
index 2671aa7e4e3..8788c2adbb0 100644
--- a/packages/react-router/src/useNavigate.tsx
+++ b/packages/react-router/src/useNavigate.tsx
@@ -8,6 +8,16 @@ import type {
   UseNavigateResult,
 } from '@tanstack/router-core'
 
+/**
+ * React hook that returns a `navigate` function for programmatic navigation.
+ * Supports updating pathname, search, hash and state with full type-safety.
+ *
+ * Options:
+ * - `from`: Default base path used to resolve relative `to` destinations.
+ *
+ * @returns A memoized `navigate` function.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useNavigateHook
+ */
 export function useNavigate<
   TRouter extends AnyRouter = RegisteredRouter,
   TDefaultFrom extends string = string,
@@ -27,6 +37,15 @@ export function useNavigate<
   ) as UseNavigateResult<TDefaultFrom>
 }
 
+/**
+ * Component that triggers a navigation when rendered. Navigation executes
+ * in an effect after mount/update.
+ *
+ * Props are the same as `NavigateOptions` used by `navigate()`.
+ *
+ * @returns null
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/navigateComponent
+ */
 export function Navigate<
   TRouter extends AnyRouter = RegisteredRouter,
   const TFrom extends string = string,