Documentation Index
Fetch the complete documentation index at: https://mintlify.com/get-convex/convex-react-query/llms.txt
Use this file to discover all available pages before exploring further.
What is this library?
@convex-dev/react-query is an adapter that lets you use TanStack Query (useQuery, useSuspenseQuery, and the rest of the TanStack Query API) with Convex real-time subscriptions.
Rather than polling for new data, results are pushed from the server to the client via WebSocket. Whenever a Convex query function’s result changes, the TanStack Query cache is updated automatically — no queryClient.invalidateQueries() calls required.
When to use it
This library is a good fit when:- You are already using TanStack Query in a Convex app and want to keep using
useQuerywithout switching to Convex’s ownuseQueryhook. - You want access to TanStack Query DevTools, caching semantics (
gcTime,placeholderData, etc.), and the broader TanStack Query ecosystem alongside Convex’s real-time data layer. - You are building a server-side rendered app with TanStack Start or a similar framework and want consistent query results during SSR.
Key concepts
ConvexQueryClient
Bridges the Convex client and the TanStack
QueryClient. Subscribes to the query cache, opens WebSocket subscriptions for each Convex query, and pushes updated results into the cache as they arrive.convexQuery()
Options factory for reactive query subscriptions. Pass it directly to
useQuery or useSuspenseQuery. Sets staleTime: Infinity and constructs the correct query key automatically.convexAction()
Options factory for Convex actions used as queries. Actions are not reactive — they follow standard TanStack Query refetch semantics rather than receiving server-pushed updates.
Re-exported hooks
useConvexMutation, useConvexAction, useConvexQuery, useConvexQueries, useConvexPaginatedQuery, useConvex, and useConvexAuth are all re-exported so you can avoid importing from convex/react directly.Peer dependencies
| Package | Version |
|---|---|
@tanstack/react-query | ^5.0.0 |
convex | ^1.34.1 |
Why staleTime: Infinity?
Both convexQuery() and convexAction() set staleTime: Infinity. For Convex queries, data is never stale — the server pushes a new result the moment the underlying data changes. There is no need for TanStack Query to re-fetch in the background; refetching would only duplicate work already handled by the WebSocket subscription.
Ready to add this to your project? See the Quickstart to get up and running in a few minutes.