Skip to main content

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.

convexQuery creates a partial query options object for subscribing to a Convex query function through TanStack Query. The query is reactive: the ConvexQueryClient pushes updates via WebSocket, and TanStack Query’s cache is updated automatically.

​
Signature

function convexQuery<ConvexQueryReference extends FunctionReference<"query">>(
  funcRef: ConvexQueryReference,
  ...argsOrSkip: ConvexQueryArgsOrSkip<ConvexQueryReference>
): (typeof argsOrSkip)[0] extends "skip"
  ? Pick<UseQueryOptions<...>, "queryKey" | "queryFn" | "staleTime" | "enabled">
  : Pick<UseSuspenseQueryOptions<...>, "queryKey" | "queryFn" | "staleTime">
The return type is compatible with both useQuery (when args may be "skip") and useSuspenseQuery (when args are not "skip").

​
Parameters

​
funcRef
FunctionReference<'query'>
required
The Convex query function reference, imported from convex/_generated/api.
​
args
FunctionArgs<typeof funcRef> | 'skip'
Arguments to pass to the query function. Pass "skip" to disable the query — this sets enabled: false in the returned options. Can be omitted entirely when the function takes no arguments (equivalent to passing an empty object).

​
Return value

Returns a partial query options object containing:
​
queryKey
["convexQuery", funcRef, args]
A stable, serializable query key. The ConvexQueryClient uses this key to manage WebSocket subscriptions.
​
staleTime
number
Always set to Infinity. Convex queries receive live updates via WebSocket, so they never go stale on their own.
​
enabled
boolean
Only present when args is "skip". Set to false to prevent the query from running.
convexQuery requires the global queryFn to be set via convexQueryClient.queryFn(). If you don’t want to configure a global default, use convexQueryClient.queryOptions() instead — it embeds the queryFn in the returned options directly.

​
Usage

Basic query: 
const { data } = useQuery(convexQuery(api.messages.list, {}));
Omitting args (when the function takes no required arguments): 
const { data } = useQuery(convexQuery(api.messages.list));
With arguments: 
const { data } = useQuery(
  convexQuery(api.messages.search, { query: "hello", limit: 5 })
);
Conditional / skip: 
const { data } = useQuery(
  convexQuery(api.messages.count, isEnabled ? {} : "skip")
);
With useSuspenseQuery: 
const { data } = useSuspenseQuery(convexQuery(api.messages.list, {}));
Spreading additional options: 
const { data } = useQuery({
  ...convexQuery(api.messages.list, {}),
  initialData: [],
  gcTime: 10_000,
});
Actions cannot be used with useSuspenseQuery. Use convexAction for Convex actions.

Build docs developers (and LLMs) love

Get started for freeTalk to us