@tanstack/react-router 1.133.27 → 1.133.32

package/src/awaited.tsx

@@ -8,6 +8,7 @@ export type AwaitOptions<T> = {
 }
 
 /** Suspend until a deferred promise resolves/rejects and return its data. */
+/** Suspend until a deferred promise resolves or rejects and return its data. */
 export function useAwaited<T>({
   promise: _promise,
 }: AwaitOptions<T>): [T, DeferredPromise<T>] {
@@ -24,6 +25,10 @@ export function useAwaited<T>({
   return [promise[TSR_DEFERRED_PROMISE].data, promise]
 }
 
+/**
+ * Component that suspends on a deferred promise and renders its child with
+ * the resolved value. Optionally provides a Suspense fallback.
+ */
 /**
  * Component that suspends on a deferred promise and renders its child with
  * the resolved value. Optionally provides a Suspense fallback.

package/src/fileRoute.ts

@@ -57,6 +57,13 @@ import type { UseRouteContextRoute } from './useRouteContext'
  * @returns A function that accepts Route options and returns a Route instance.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createFileRouteFunction
  */
+/**
+ * Creates a file-based Route factory for a given path.
+ * Used by file-based routing to associate a file with a route. The returned
+ * function accepts standard route options; the path is typically auto-managed
+ * by the generator.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createFileRouteFunction
+ */
 export function createFileRoute<
   TFilePath extends keyof FileRoutesByPath,
   TParentRoute extends AnyRoute = FileRoutesByPath[TFilePath]['parentRoute'],
@@ -85,6 +92,10 @@ export function createFileRoute<
   @deprecated It's no longer recommended to use the `FileRoute` class directly.
   Instead, use `createFileRoute('/path/to/file')(options)` to create a file route.
 */
+/**
+  @deprecated It's no longer recommended to use the `FileRoute` class directly.
+  Instead, use `createFileRoute('/path')(options)` to create a file route.
+*/
 export class FileRoute<
   TFilePath extends keyof FileRoutesByPath,
   TParentRoute extends AnyRoute = FileRoutesByPath[TFilePath]['parentRoute'],
@@ -184,6 +195,10 @@ export class FileRoute<
   Instead, place the loader function in the the main route file, inside the
   `createFileRoute('/path/to/file)(options)` options.
 */
+/**
+  @deprecated It's recommended not to split loaders into separate files.
+  Instead, place the loader function in the main route file via `createFileRoute`.
+*/
 export function FileRouteLoader<
   TFilePath extends keyof FileRoutesByPath,
   TRoute extends FileRoutesByPath[TFilePath]['preLoaderRoute'],
@@ -308,6 +323,10 @@ export class LazyRoute<TRoute extends AnyRoute> {
  * @returns A function that accepts lazy route options and returns a `LazyRoute`.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyRouteFunction
  */
+/**
+ * Create a lazily-configurable code-based route stub by ID.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyRouteFunction
+ */
 export function createLazyRoute<
   TRouter extends AnyRouter = RegisteredRouter,
   TId extends string = string,
@@ -343,6 +362,10 @@ export function createLazyRoute<
  * @returns A function that accepts lazy route options and returns a `LazyRoute`.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyFileRouteFunction
  */
+/**
+ * Create a lazily-configurable file-based route stub by file path.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyFileRouteFunction
+ */
 export function createLazyFileRoute<
   TFilePath extends keyof FileRoutesByPath,
   TRoute extends FileRoutesByPath[TFilePath]['preLoaderRoute'],

package/src/link.tsx

@@ -243,7 +243,9 @@ export function useLinkProps<
   // The click handler
   const handleClick = (e: React.MouseEvent) => {
     // Check actual element's target attribute as fallback
-    const elementTarget = (e.currentTarget as HTMLAnchorElement).target
+    const elementTarget = (
+      e.currentTarget as HTMLAnchorElement | SVGAElement
+    ).getAttribute('target')
     const effectiveTarget = target !== undefined ? target : elementTarget
 
     if (
@@ -615,6 +617,21 @@ export type LinkOptionsFn<TComp> = <
   options: LinkOptionsFnOptions<TOptions, TComp, TRouter>,
 ) => TOptions
 
+/**
+ * Validate and reuse navigation options for `Link`, `navigate` or `redirect`.
+ * Accepts a literal options object and returns it typed for later spreading.
+ * @example
+ * const opts = linkOptions({ to: '/dashboard', search: { tab: 'home' } })
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/linkOptions
+ */
 export const linkOptions: LinkOptionsFn<'a'> = (options) => {
   return options as any
 }
+
+/**
+ * Type-check a literal object for use with `Link`, `navigate` or `redirect`.
+ * Use to validate and reuse navigation options across your app.
+ * @example
+ * const opts = linkOptions({ to: '/dashboard', search: { tab: 'home' } })
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/linkOptions
+ */

package/src/router.ts

@@ -88,6 +88,11 @@ declare module '@tanstack/router-core' {
  * @returns A Router instance to be provided to `RouterProvider`.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createRouterFunction
  */
+/**
+ * Create a new React router instance from `RouterOptions`.
+ * Pass the resulting router to `RouterProvider`.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createRouterFunction
+ */
 export const createRouter: CreateRouterFn = (options) => {
   return new Router(options)
 }

package/src/useLoaderData.tsx

@@ -65,6 +65,10 @@ export type UseLoaderDataRoute<out TId> = <
  * @returns The loader data (or selected value) for the matched route.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useLoaderDataHook
  */
+/**
+ * Read and select the current route's loader data with type‑safety.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useLoaderDataHook
+ */
 export function useLoaderData<
   TRouter extends AnyRouter = RegisteredRouter,
   const TFrom extends string | undefined = undefined,

package/src/useLoaderDeps.tsx

@@ -51,6 +51,10 @@ export type UseLoaderDepsRoute<out TId> = <
  * @returns The loader deps (or selected value) for the matched route.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useLoaderDepsHook
  */
+/**
+ * Read and select the current route's loader dependencies object.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useLoaderDepsHook
+ */
 export function useLoaderDeps<
   TRouter extends AnyRouter = RegisteredRouter,
   const TFrom extends string | undefined = undefined,

package/src/useLocation.tsx

@@ -37,6 +37,11 @@ export type UseLocationResult<
  * @returns The current location (or selected value).
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useLocationHook
  */
+/**
+ * Read the current location from the router state with optional selection.
+ * Useful for subscribing to just the pieces of location you care about.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useLocationHook
+ */
 export function useLocation<
   TRouter extends AnyRouter = RegisteredRouter,
   TSelected = unknown,

package/src/useMatch.tsx

@@ -77,14 +77,6 @@ export type UseMatchResult<
 
 /**
  * Read and select the nearest or targeted route match.
- *
- * Options:
- * - `from`/`strict`: Target a specific route ID and control union vs. exact typing
- * - `select`: Project the match object to a derived value
- * - `shouldThrow`: Throw if the match is not found in strict contexts
- * - `structuralSharing`: Enable structural sharing for stable references
- *
- * @returns The active match (or selected value).
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useMatchHook
  */
 export function useMatch<

package/src/useParams.tsx

@@ -73,6 +73,10 @@ export type UseParamsRoute<out TFrom> = <
  * @returns The params object (or selected value) for the matched route.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useParamsHook
  */
+/**
+ * Access the current route's path parameters with type-safety.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useParamsHook
+ */
 export function useParams<
   TRouter extends AnyRouter = RegisteredRouter,
   const TFrom extends string | undefined = undefined,

package/src/useRouter.tsx

@@ -13,6 +13,11 @@ import type { AnyRouter, RegisteredRouter } from '@tanstack/router-core'
  * @returns The registered router instance.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useRouterHook
  */
+/**
+ * Access the current TanStack Router instance from React context.
+ * Must be used within a `RouterProvider`.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useRouterHook
+ */
 export function useRouter<TRouter extends AnyRouter = RegisteredRouter>(opts?: {
   warn?: boolean
 }): TRouter {

package/src/useRouterState.tsx

@@ -40,6 +40,11 @@ export type UseRouterStateResult<
  * @returns The selected router state (or the full state by default).
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useRouterStateHook
  */
+/**
+ * Subscribe to the router's state store with optional selection and
+ * structural sharing for render optimization.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useRouterStateHook
+ */
 export function useRouterState<
   TRouter extends AnyRouter = RegisteredRouter,
   TSelected = unknown,

package/src/useSearch.tsx

@@ -73,6 +73,10 @@ export type UseSearchRoute<out TFrom> = <
  * @returns The search object (or selected value) for the matched route.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useSearchHook
  */
+/**
+ * Read and select the current route's search parameters with type-safety.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useSearchHook
+ */
 export function useSearch<
   TRouter extends AnyRouter = RegisteredRouter,
   const TFrom extends string | undefined = undefined,