Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/framework/react/api/router.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
40 changes: 33 additions & 7 deletions docs/framework/react/api/router/RouteApiClass.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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<TSelected = TLoaderDeps>(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
Expand Down
2 changes: 1 addition & 1 deletion docs/framework/react/api/router/getRouteApiFunction.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
51 changes: 51 additions & 0 deletions docs/framework/react/api/router/useLoaderDepsHook.md
Original file line number Diff line number Diff line change
@@ -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,
})

// ...
}
```
2 changes: 1 addition & 1 deletion docs/framework/react/api/router/useParamsHook.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
47 changes: 47 additions & 0 deletions docs/framework/react/api/router/useRouteContextHook.md
Original file line number Diff line number Diff line change
@@ -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

// ...
}
```
23 changes: 23 additions & 0 deletions docs/framework/react/api/router/useRouterHook.md
Original file line number Diff line number Diff line change
@@ -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

// ...
}
```
40 changes: 40 additions & 0 deletions docs/framework/react/api/router/useRouterStateHook.md
Original file line number Diff line number Diff line change
@@ -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

// ...
}
```
59 changes: 59 additions & 0 deletions docs/framework/react/api/router/useSearchHook.md
Original file line number Diff line number Diff line change
@@ -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<FullSearchSchema>` 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<FullSearchSchema>

// ...
}
```