diff --git a/packages/react-router/src/RouterProvider.tsx b/packages/react-router/src/RouterProvider.tsx index 9c845df0969..fd2aeb1eef2 100644 --- a/packages/react-router/src/RouterProvider.tsx +++ b/packages/react-router/src/RouterProvider.tsx @@ -7,6 +7,10 @@ import type { RouterOptions, } from '@tanstack/router-core' +/** + * Low-level provider that places the router into React context and optionally + * updates router options from props. Most apps should use `RouterProvider`. + */ export function RouterContextProvider< TRouter extends AnyRouter = RegisteredRouter, TDehydrated extends Record = Record, @@ -44,6 +48,15 @@ export function RouterContextProvider< return provider } +/** + * Top-level component that renders the active route matches and provides the + * router to the React tree via context. + * + * Accepts the same options as `createRouter` via props to update the router + * instance after creation. + * + * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createRouterFunction + */ export function RouterProvider< TRouter extends AnyRouter = RegisteredRouter, TDehydrated extends Record = Record, diff --git a/packages/react-router/src/link.tsx b/packages/react-router/src/link.tsx index 92ee2d82426..dca40090508 100644 --- a/packages/react-router/src/link.tsx +++ b/packages/react-router/src/link.tsx @@ -539,7 +539,7 @@ export function createLink( * 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 diff --git a/packages/react-router/src/useParams.tsx b/packages/react-router/src/useParams.tsx index 7ff3d3934db..444eee7a416 100644 --- a/packages/react-router/src/useParams.tsx +++ b/packages/react-router/src/useParams.tsx @@ -61,6 +61,18 @@ export type UseParamsRoute = < StructuralSharingOption, ) => UseParamsResult +/** + * 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, diff --git a/packages/react-router/src/useRouter.tsx b/packages/react-router/src/useRouter.tsx index 474beb09f8a..abfefecaa3e 100644 --- a/packages/react-router/src/useRouter.tsx +++ b/packages/react-router/src/useRouter.tsx @@ -3,6 +3,16 @@ 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 + */ export function useRouter(opts?: { warn?: boolean }): TRouter { diff --git a/packages/react-router/src/useRouterState.tsx b/packages/react-router/src/useRouterState.tsx index a4244e25bcc..08a7c7b9b86 100644 --- a/packages/react-router/src/useRouterState.tsx +++ b/packages/react-router/src/useRouterState.tsx @@ -28,6 +28,18 @@ export type UseRouterStateResult< TSelected, > = unknown extends TSelected ? RouterState : 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, diff --git a/packages/react-router/src/useSearch.tsx b/packages/react-router/src/useSearch.tsx index 5ab2b8cb8d0..46b6e516424 100644 --- a/packages/react-router/src/useSearch.tsx +++ b/packages/react-router/src/useSearch.tsx @@ -61,6 +61,18 @@ export type UseSearchRoute = < StructuralSharingOption, ) => UseSearchResult +/** + * 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,