diff --git a/docs/framework/react/api/router.md b/docs/framework/react/api/router.md index c1fd898354c..5d68c8fe3dc 100644 --- a/docs/framework/react/api/router.md +++ b/docs/framework/react/api/router.md @@ -32,12 +32,17 @@ title: Router API - [`useChildMatches()`](./api/router/useChildMatchesHook) - [`useLinkProps()`](./api/router/useLinkPropsHook) - [`useLoaderData()`](./api/router/useLoaderDataHook) + - [`useLoaderDeps()`](./api/router/useLoaderDepsHook) - [`useMatch()`](./api/router/useMatchHook) - [`useMatchRoute()`](./api/router/useMatchRouteHook) - [`useMatches()`](./api/router/useMatchesHook) - [`useNavigate()`](./api/router/useNavigateHook) - [`useParentMatches()`](./api/router/useParentMatchesHook) - [`useParams()`](./api/router/useParamsHook) + - [`useRouteContext()`](./api/router/useRouteContextHook) + - [`useRouter()`](./api/router/useRouterHook) + - [`useRouterState()`](./api/router/useRouterStateHook) + - [`useSearch()`](./api/router/useSearchHook) - Types - [`ActiveLinkOptions Type`](./api/router/ActiveLinkOptionsType) - [`AllParams Type`](./api/router/AllParamsType) diff --git a/docs/framework/react/api/router/RouteApiClass.md b/docs/framework/react/api/router/RouteApiClass.md index 836d568bad2..cefbe9807b5 100644 --- a/docs/framework/react/api/router/RouteApiClass.md +++ b/docs/framework/react/api/router/RouteApiClass.md @@ -5,7 +5,7 @@ title: RouteApi class > 🚧 The `RouteApiClass` class is deprecated and will be removed in the next major version of TanStack Router. Please use the [`getRouteApi`](./api/router/getRouteApiFunction) function instead. The constructor and methods associated with this class will be implemented on its functional counterpart in the next major release. -The `RouteApi` class provides type-safe version of common hooks like `useParams`, `useLoaderData`, `useRouteContext`, and `useSearch` that are pre-bound to a specific route ID and corresponding registered route types. +The `RouteApi` class provides type-safe version of common hooks like `useParams`, `useSearch`, `useRouteContext`, `useNavigate`, `useLoaderData`, and `useLoaderDeps` that are pre-bound to a specific route ID and corresponding registered route types. ## Constructor options @@ -19,7 +19,7 @@ The `RouteApi` constructor accepts a single argument: the `options` that will be ## Constructor returns -- A `RouteApi` instance that is pre-bound to the route ID that the `RouteApi` constructor was called with that provides type-safe versions of common hooks like `useParams`, `useLoaderData`, `useRouteContext`, and `useSearch`. +- A `RouteApi` instance that is pre-bound to the route ID that the `RouteApi` constructor was called with that provides type-safe versions of common hooks like `useParams`, `useSearch`, `useRouteContext`, `useNavigate`, `useLoaderData`, and `useLoaderDeps`. ## `RouteApi` properties and methods @@ -33,7 +33,7 @@ The `RouteApi` class implements the following properties and methods: }): TSelected ``` -- A type-safe version of the `useMatch` hook that is pre-bound to the route ID that the `RouteApi` instance was created with. +- A type-safe version of the [`useMatch`](./api/router/useMatchHook) hook that is pre-bound to the route ID that the `RouteApi` instance was created with. - Options - `opts.select` - Optional @@ -51,7 +51,7 @@ The `RouteApi` class implements the following properties and methods: }): TSelected ``` -- A type-safe version of the `useRouteContext` hook that is pre-bound to the route ID that the `RouteApi` instance was created with. +- A type-safe version of the [`useRouteContext`](./api/router/useRouteContextHook) hook that is pre-bound to the route ID that the `RouteApi` instance was created with. - Options - `opts.select` - Optional @@ -69,7 +69,7 @@ The `RouteApi` class implements the following properties and methods: }): TSelected ``` -- A type-safe version of the `useSearch` hook that is pre-bound to the route ID that the `RouteApi` instance was created with. +- A type-safe version of the [`useSearch`](./api/router/useSearchHook) hook that is pre-bound to the route ID that the `RouteApi` instance was created with. - Options - `opts.select` - Optional @@ -87,7 +87,7 @@ The `RouteApi` class implements the following properties and methods: }): TSelected ``` -- A type-safe version of the `useParams` hook that is pre-bound to the route ID that the `RouteApi` instance was created with. +- A type-safe version of the [`useParams`](./api/router/useParamsHook) hook that is pre-bound to the route ID that the `RouteApi` instance was created with. - Options - `opts.select` - Optional @@ -105,7 +105,7 @@ The `RouteApi` class implements the following properties and methods: }): TSelected ``` -- A type-safe version of the `useLoaderData` hook that is pre-bound to the route ID that the `RouteApi` instance was created with. +- A type-safe version of the [`useLoaderData`](./api/router/useLoaderDataHook) hook that is pre-bound to the route ID that the `RouteApi` instance was created with. - Options - `opts.select` - Optional @@ -115,6 +115,32 @@ The `RouteApi` class implements the following properties and methods: - If a `select` function is provided, the return value of the `select` function. - If no `select` function is provided, the `TLoaderData` object or a loosened version of the `TLoaderData` object if `opts.strict` is `false`. +### `useLoaderDeps` method + +```tsx + useLoaderDeps(opts?: { + select?: (search: TLoaderDeps) => TSelected + }): TSelected +``` + +- A type-safe version of the [`useLoaderDeps`](./api/router/useLoaderDepsHook) hook that is pre-bound to the route ID that the `RouteApi` instance was created with. +- Options + - `opts.select` + - Optional + - `(match: TLoaderDeps) => TSelected` + - If supplied, this function will be called with the route match and the return value will be returned from `useLoaderDeps`. +- Returns + - If a `select` function is provided, the return value of the `select` function. + - If no `select` function is provided, the `TLoaderDeps` object. + +### `useNavigate` method + +```tsx + useNavigate(): // navigate function +``` + +- A type-safe version of [`useNavigate`](./api/router/useNavigateHook) that is pre-bound to the route ID that the `RouteApi` instance was created with. + ## Examples ```tsx diff --git a/docs/framework/react/api/router/getRouteApiFunction.md b/docs/framework/react/api/router/getRouteApiFunction.md index 2675c41abb0..05fc3dcea95 100644 --- a/docs/framework/react/api/router/getRouteApiFunction.md +++ b/docs/framework/react/api/router/getRouteApiFunction.md @@ -3,7 +3,7 @@ id: getRouteApiFunction title: getRouteApi function --- -The `getRouteApi` function provides type-safe version of common hooks like `useParams`, `useLoaderData`, `useRouteContext`, and `useSearch` that are pre-bound to a specific route ID and corresponding registered route types. +The `getRouteApi` function provides type-safe version of common hooks like `useParams`, `useSearch`, `useRouteContext`, `useNavigate`, `useLoaderData`, and `useLoaderDeps` that are pre-bound to a specific route ID and corresponding registered route types. ## getRouteApi options diff --git a/docs/framework/react/api/router/useLoaderDepsHook.md b/docs/framework/react/api/router/useLoaderDepsHook.md new file mode 100644 index 00000000000..68ff17700cc --- /dev/null +++ b/docs/framework/react/api/router/useLoaderDepsHook.md @@ -0,0 +1,51 @@ +--- +id: useLoaderDepsHook +title: useLoaderDeps hook +--- + +The `useLoaderDeps` hook is a hook that returns an object with the dependencies that are used to trigger the `loader` for a given route. + +## useParams options + +The `useParams` hook accepts an `options` object. + +### `opts.from` option + +- Type: `string` +- Required +- The RouteID or path to get the loader dependencies from. + +### `opts.select` option + +- Type: `(deps: TLoaderDeps) => TSelected` +- Optional +- If supplied, this function will be called with the loader dependencies object and the return value will be returned from `useLoaderDeps`. + +## useLoaderDeps returns + +- An object of the loader dependencies or `TSelected` if a `select` function is provided. + +## Examples + +```tsx +import { useLoaderDeps } from '@tanstack/react-router' + +const routeApi = getRouteApi('/posts/$postId') + +function Component() { + const deps = useLoaderDeps({ from: '/posts/$postId' }) + + // OR + + const routeDeps = routeApi.useLoaderDeps() + + // OR + + const postId = useLoaderDeps({ + from: '/posts', + select: (deps) => deps.view, + }) + + // ... +} +``` diff --git a/docs/framework/react/api/router/useParamsHook.md b/docs/framework/react/api/router/useParamsHook.md index 9028e62c4e3..83e9297414f 100644 --- a/docs/framework/react/api/router/useParamsHook.md +++ b/docs/framework/react/api/router/useParamsHook.md @@ -1,6 +1,6 @@ --- id: useParamsHook -title: useParams +title: useParams hook --- The `useParams` method returns all of the path parameters that were parsed for the closest match and all of its parent matches. diff --git a/docs/framework/react/api/router/useRouteContextHook.md b/docs/framework/react/api/router/useRouteContextHook.md new file mode 100644 index 00000000000..bf2651d633b --- /dev/null +++ b/docs/framework/react/api/router/useRouteContextHook.md @@ -0,0 +1,47 @@ +--- +id: useRouteContextHook +title: useRouteContext hook +--- + +The `useRouteContext` method is a hook that returns the current context for the current route. This hook is useful for accessing the current route context in a component. + +## useRouteContext options + +The `useRouteContext` hook accepts an `options` object. + +### `opts.from` option + +- Type: `string` +- Required +- The RouteID to match the route context from. + +### `opts.select` option + +- Type: `(context: RouteContext) => TSelected` +- Optional +- If supplied, this function will be called with the route context object and the return value will be returned from `useRouteContext`. + +## useRouteContext returns + +- The current context for the current route or `TSelected` if a `select` function is provided. + +## Examples + +```tsx +import { useRouteContext } from '@tanstack/react-router' + +function Component() { + const context = useRouteContext({ from: '/posts/$postId' }) + // ^ RouteContext + + // OR + + const selected = useRouteContext({ + from: '/posts/$postId', + select: (context) => context.postId, + }) + // ^ string + + // ... +} +``` diff --git a/docs/framework/react/api/router/useRouterHook.md b/docs/framework/react/api/router/useRouterHook.md new file mode 100644 index 00000000000..f66d342c0d2 --- /dev/null +++ b/docs/framework/react/api/router/useRouterHook.md @@ -0,0 +1,23 @@ +--- +id: useRouterHook +title: useRouter hook +--- + +The `useRouter` method is a hook that returns the current instance of [`Router`](./api/router/RouterClass) from context. This hook is useful for accessing the router instance in a component. + +## useRouter returns + +- The current [`Router`](./api/router/RouterClass) instance. + +## Examples + +```tsx +import { useRouter } from '@tanstack/react-router' + +function Component() { + const router = useRouter() + // ^ Router + + // ... +} +``` diff --git a/docs/framework/react/api/router/useRouterStateHook.md b/docs/framework/react/api/router/useRouterStateHook.md new file mode 100644 index 00000000000..cfd705ee5fc --- /dev/null +++ b/docs/framework/react/api/router/useRouterStateHook.md @@ -0,0 +1,40 @@ +--- +id: useRouterStateHook +title: useRouterState hook +--- + +The `useRouterState` method is a hook that returns the current internal state of the router. This hook is useful for accessing the current state of the router in a component. + +## useRouterState options + +The `useRouterState` hook accepts an optional `options` object. + +### `opts.select` option + +- Type: `(state: RouterState) => TSelected` +- Optional +- If supplied, this function will be called with the [RouterState](./api/router/RouterStateType) object and the return value will be returned from `useRouterState`. + +## useRouterState returns + +- The current [RouterState](./api/router/RouterStateType) object or `TSelected` if a `select` function is provided. + +## Examples + +```tsx +import { useRouterState } from '@tanstack/react-router' + +function Component() { + const state = useRouterState() + // ^ RouterState + + // OR + + const selected = useRouterState({ + select: (state) => state.location, + }) + // ^ ParsedLocation + + // ... +} +``` diff --git a/docs/framework/react/api/router/useSearchHook.md b/docs/framework/react/api/router/useSearchHook.md new file mode 100644 index 00000000000..586ce2e4d27 --- /dev/null +++ b/docs/framework/react/api/router/useSearchHook.md @@ -0,0 +1,59 @@ +--- +id: useSearchHook +title: useSearch hook +--- + +The `useSearch` method is a hook that returns the current search query parameters as an object for the current location. This hook is useful for accessing the current search string and query parameters in a component. + +## useSearch options + +The `useSearch` hook accepts an `options` object. + +### `opts.from` option + +- Type: `string` +- Required +- The RouteID to match the search query parameters from. + +### `opts.select` option + +- Type: `(search: SelectedSearchSchema) => TSelected` +- Optional +- If supplied, this function will be called with the search object and the return value will be returned from `useSearch`. + +### `opts.strict` option + +- Type: `boolean` +- Optional - `default: true` +- If `false`, the `opts.from` option will be ignored and types will be loosened to `Partial` to reflect the shared types of all search query parameters. + +## useSearch returns + +- If `opts.from` is provided, an object of the search query parameters for the current location or `TSelected` if a `select` function is provided. +- If `opts.strict` is `false`, an object of the search query parameters for the current location or `TSelected` if a `select` function is provided. + +## Examples + +```tsx +import { useSearch } from '@tanstack/react-router' + +function Component() { + const search = useSearch({ from: '/posts/$postId' }) + // ^ FullSearchSchema + + // OR + + const selected = useSearch({ + from: '/posts/$postId', + select: (search) => search.postView, + }) + // ^ string + + // OR + + const looseSearch = useSearch({ strict: false }) + // ^ Partial + + // ... +} +```