@tanstack/react-router 1.133.20 → 1.133.22

package/src/fileRoute.ts

@@ -35,6 +35,17 @@ import type { UseLoaderDepsRoute } from './useLoaderDeps'
 import type { UseLoaderDataRoute } from './useLoaderData'
 import type { UseRouteContextRoute } from './useRouteContext'
 
+/**
+ * Creates a file-based Route factory for a given path.
+ *
+ * Used by TanStack Router's file-based routing to associate a file with a
+ * route. The returned function accepts standard route options. In normal usage
+ * the `path` string is inserted and maintained by the `tsr` generator.
+ *
+ * @param path File path literal for the route (usually auto-generated).
+ * @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.
  *
@@ -66,6 +77,10 @@ export function createFileRoute<
   }).createRoute
 }
 
+/** 
+  @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/to/file')(options)` to create a file route.
@@ -159,6 +174,11 @@ export class FileRoute<
   }
 }
 
+/** 
+  @deprecated It's recommended not to split loaders into separate files.
+  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 the main route file, inside the
@@ -264,6 +284,18 @@ export class LazyRoute<TRoute extends AnyRoute> {
   }
 }
 
+/**
+ * Creates a lazily-configurable code-based route stub by ID.
+ *
+ * Use this for code-splitting with code-based routes. The returned function
+ * accepts only non-critical route options like `component`, `pendingComponent`,
+ * `errorComponent`, and `notFoundComponent` which are applied when the route
+ * is matched.
+ *
+ * @param id Route ID string literal to associate with the lazy route.
+ * @returns A function that accepts lazy route options and returns a `LazyRoute`.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyRouteFunction
+ */
 /**
  * Creates a lazily-configurable code-based route stub by ID.
  *
@@ -289,6 +321,17 @@ export function createLazyRoute<
   }
 }
 
+/**
+ * Creates a lazily-configurable file-based route stub by file path.
+ *
+ * Use this for code-splitting with file-based routes (eg. `.lazy.tsx` files).
+ * The returned function accepts only non-critical route options like
+ * `component`, `pendingComponent`, `errorComponent`, and `notFoundComponent`.
+ *
+ * @param id File path literal for the route file.
+ * @returns A function that accepts lazy route options and returns a `LazyRoute`.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyFileRouteFunction
+ */
 /**
  * Creates a lazily-configurable file-based route stub by file path.
  *

package/src/lazyRouteComponent.tsx

@@ -2,6 +2,15 @@ import * as React from 'react'
 import { isModuleNotFoundError } from '@tanstack/router-core'
 import type { AsyncRouteComponent } from './route'
 
+/**
+ * Wrap a dynamic import to create a route component that supports
+ * `.preload()` and friendly reload-on-module-missing behavior.
+ *
+ * @param importer Function returning a module promise
+ * @param exportName Named export to use (default: `default`)
+ * @returns A lazy route component compatible with TanStack Router
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/lazyRouteComponentFunction
+ */
 export function lazyRouteComponent<
   T extends Record<string, any>,
   TKey extends keyof T = 'default',

package/src/link.tsx

@@ -25,6 +25,18 @@ import type {
   ValidateLinkOptionsArray,
 } from './typePrimitives'
 
+/**
+ * Build anchor-like props for declarative navigation and preloading.
+ *
+ * Returns stable `href`, event handlers and accessibility props derived from
+ * router options and active state. Used internally by `Link` and custom links.
+ *
+ * Options cover `to`, `params`, `search`, `hash`, `state`, `preload`,
+ * `activeProps`, `inactiveProps`, and more.
+ *
+ * @returns React anchor props suitable for `<a>` or custom components.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useLinkPropsHook
+ */
 export function useLinkProps<
   TRouter extends AnyRouter = RegisteredRouter,
   const TFrom extends string = string,
@@ -539,7 +551,7 @@ export function createLink<const TComp>(
  * Handles path, search, hash and state updates with optional route preloading
  * and active-state styling.
  *
- * Non-obvious props include:
+ * Props:
  * - `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

package/src/route.tsx

@@ -78,6 +78,24 @@ declare module '@tanstack/router-core' {
   }
 }
 
+/**
+ * Returns a route-specific API that exposes type-safe hooks pre-bound
+ * to a single route ID. Useful for consuming a route's APIs from files
+ * where the route object isn't directly imported (e.g. code-split files).
+ *
+ * @param id Route ID string literal for the target route.
+ * @returns A `RouteApi` instance bound to the given route ID.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/getRouteApiFunction
+ */
+/**
+ * Returns a route-specific API that exposes type-safe hooks pre-bound
+ * to a single route ID. Useful for consuming a route's APIs from files
+ * where the route object isn't directly imported (e.g. code-split files).
+ *
+ * @param id Route ID string literal for the target route.
+ * @returns A `RouteApi` instance bound to the given route ID.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/getRouteApiFunction
+ */
 /**
  * Returns a route-specific API that exposes type-safe hooks pre-bound
  * to a single route ID. Useful for consuming a route's APIs from files

package/src/useLoaderData.tsx

@@ -54,6 +54,17 @@ export type UseLoaderDataRoute<out TId> = <
     StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
 ) => UseLoaderDataResult<TRouter, TId, true, TSelected>
 
+/**
+ * Read and select the current route's loader data with type‑safety.
+ *
+ * Options:
+ * - `from`/`strict`: Choose which route's data to read and strictness
+ * - `select`: Map the loader data to a derived value
+ * - `structuralSharing`: Enable structural sharing for stable references
+ *
+ * @returns The loader data (or selected value) for the matched route.
+ * @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

@@ -40,6 +40,17 @@ export type UseLoaderDepsRoute<out TId> = <
     StructuralSharingOption<TRouter, TSelected, false>,
 ) => UseLoaderDepsResult<TRouter, TId, TSelected>
 
+/**
+ * Read and select the current route's loader dependencies object.
+ *
+ * Options:
+ * - `from`: Choose which route's loader deps to read
+ * - `select`: Map the deps to a derived value
+ * - `structuralSharing`: Enable structural sharing for stable references
+ *
+ * @returns The loader deps (or selected value) for the matched route.
+ * @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

@@ -26,6 +26,17 @@ export type UseLocationResult<
   ? RouterState<TRouter['routeTree']>['location']
   : TSelected
 
+/**
+ * Read the current location from the router state with optional selection.
+ * Useful for subscribing to just the pieces of location you care about.
+ *
+ * Options:
+ * - `select`: Project the `location` object to a derived value
+ * - `structuralSharing`: Enable structural sharing for stable references
+ *
+ * @returns The current location (or selected value).
+ * @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

@@ -75,6 +75,18 @@ export type UseMatchResult<
     : MakeRouteMatchUnion<TRouter>
   : TSelected
 
+/**
+ * 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<
   TRouter extends AnyRouter = RegisteredRouter,
   const TFrom extends string | undefined = undefined,

package/src/useNavigate.tsx

@@ -9,13 +9,17 @@ import type {
 } 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.
+ * 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`: Default base path used to resolve relative `to` destinations.
+ * - `from`: Optional route base used to resolve relative `to` paths.
  *
- * @returns A memoized `navigate` function.
+ * @returns A function that accepts `NavigateOptions`.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useNavigateHook
  */
 export function useNavigate<

package/src/useParams.tsx

@@ -61,6 +61,18 @@ export type UseParamsRoute<out TFrom> = <
     StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
 ) => UseParamsResult<TRouter, TFrom, true, TSelected>
 
+/**
+ * Access the current route's path parameters with type-safety.
+ *
+ * Options:
+ * - `from`/`strict`: Specify the matched route and whether to enforce strict typing
+ * - `select`: Project the params object to a derived value for memoized renders
+ * - `structuralSharing`: Enable structural sharing for stable references
+ * - `shouldThrow`: Throw if the route is not found in strict contexts
+ *
+ * @returns The params object (or selected value) for the matched route.
+ * @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

@@ -3,6 +3,26 @@ import warning from 'tiny-warning'
 import { getRouterContext } from './routerContext'
 import type { AnyRouter, RegisteredRouter } from '@tanstack/router-core'
 
+/**
+ * Access the current TanStack Router instance from React context.
+ * Must be used within a `RouterProvider`.
+ *
+ * Options:
+ * - `warn`: Log a warning if no router context is found (default: true).
+ *
+ * @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`.
+ *
+ * Options:
+ * - `warn`: Log a warning if no router context is found (default: true).
+ *
+ * @returns The registered router instance.
+ * @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

@@ -28,6 +28,18 @@ export type UseRouterStateResult<
   TSelected,
 > = unknown extends TSelected ? RouterState<TRouter['routeTree']> : TSelected
 
+/**
+ * Subscribe to the router's state store with optional selection and
+ * structural sharing for render optimization.
+ *
+ * Options:
+ * - `select`: Project the full router state to a derived slice
+ * - `structuralSharing`: Replace-equal semantics for stable references
+ * - `router`: Read state from a specific router instance instead of context
+ *
+ * @returns The selected router state (or the full state by default).
+ * @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

@@ -61,6 +61,18 @@ export type UseSearchRoute<out TFrom> = <
     StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
 ) => UseSearchResult<TRouter, TFrom, true, TSelected>
 
+/**
+ * Read and select the current route's search parameters with type-safety.
+ *
+ * Options:
+ * - `from`/`strict`: Control which route's search is read and how strictly it's typed
+ * - `select`: Map the search object to a derived value for render optimization
+ * - `structuralSharing`: Enable structural sharing for stable references
+ * - `shouldThrow`: Throw when the route is not found (strict contexts)
+ *
+ * @returns The search object (or selected value) for the matched route.
+ * @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,