---
title: Queries and cache utilities
description: Call finite client-exposed routes with native TanStack Query types.
pagination: false
sidebar:
  icon: route
---

Call a backend operation from React using the contract generated from your application's routes.

> **Before you begin**
>
> Complete [frontend installation and contract pull](/docs/modules/client) before using this guide.
> Keep its selected React/query peers and generated declarations in the frontend package.

## Query finite routes

`useRoute`, `useInfiniteRoute`, `useSuspenseRoute`, and `useRouteUtils` accept only finite exposed
routes. Inputs, outputs, errors, selection, page parameters, signals, and query options are inferred
from generated declarations.

The [Hello route](/docs/modules/service/routes#when-to-use-defineroute) generates `GET /hello`.
Import `useRoute` and `useRelkitClient` from `@relkit/client/react`, then render this component
under the provider from the [Frontend guide](/guides/frontend/connect-react):

```tsx title="src/Greeting.tsx — component body"
/** Displays the typed Hello result after the provider resolves backend identity.
 * @returns Loading, connection failure, request failure, or the successful greeting. */
export function Greeting() {
  const { status } = useRelkitClient();
  const greeting = useRoute("GET /hello", { input: { name: "RELKIT" } });

  if (status === "application-updated") {
    return <p role="alert">The API changed. Pull its contract and restart the frontend.</p>;
  }
  if (status === "error") return <p role="alert">Cannot connect to the API.</p>;
  if (greeting.isError) return <p role="alert">{greeting.error.message}</p>;
  if (greeting.isPending) return <p role="status">Loading greeting…</p>;
  return <h1>{greeting.data.message}</h1>;
}
```

The input and `data.message` follow the backend's schemas. An invalid selector or input fails
typechecking after the generated declarations are included. `GET /hello` is the procedure selector;
the client still uses RPC rather than constructing a REST request.

## Choose query helpers

| API                                                              | Use it when                                                                                                                                         |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`useRoute`](/docs/api/client#useroute)                          | The component renders loading, error, and success states.                                                                                           |
| [`useSuspenseRoute`](/docs/api/client#usesuspenseroute)          | A ready provider and your Suspense/error boundaries own loading and failure. It throws while the provider is not ready.                             |
| [`useInfiniteRoute`](/docs/api/client#useinfiniteroute)          | The backend already accepts pagination input; supply `initialPageParam`, `input(page)`, and `getNextPageParam`. It does not add backend pagination. |
| [`useRouteUtils`](/docs/api/client#userouteutils)                | You need the selected procedure's underlying query/mutation option builders.                                                                        |
| [`createTanstackQueryUtils`](/docs/api/client#all-exported-apis) | An application outside the RELKIT React hooks owns its QueryClient and identity lifecycle. Import it from `@relkit/client/tanstack-query`.          |

For the standalone query adapter, install its selected peers in the caller package:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @opentelemetry/api@1.9.1 @orpc/tanstack-query@2.0.0-beta.31 @relkit/client@0.8.2 '@tanstack/query-core@>=5.80.2'
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

The React installation already includes these peers. Its managed hooks use identity-scoped
[`relkitKey`](/docs/api/client#relkitkey) keys. The underlying option builders do not automatically
produce those keys: use a managed query's `refetch()` for a simple refresh, or preserve the full
provider scope when interacting with its cache. See [server rendering](/docs/modules/client/ssr)
for the same requirement when prefetching.

## Keep streams separate

Routes with streaming output are deliberately absent from these selectors. Use `useStream` instead.
Routes marked `client: false` have neither a route-ID RPC procedure nor a URL alias.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/client` API](/docs/api/client)
- [`@relkit/routes` API](/docs/api/routes)

- [`apps/docs/examples/frontend/app.tsx`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/app.tsx)