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.

convexAction creates a partial query options object for calling a Convex action through TanStack Query. Unlike convexQuery, actions are not reactive — they do not receive pushed updates from the Convex server and follow standard TanStack Query fetch semantics.
Convex actions are not reactive. They will not receive live updates pushed from the server. Data is only refreshed via standard TanStack Query mechanisms such as manual refetch, window focus refetching, or stale time expiry. Actions cannot be used with useSuspenseQuery.

​
Signature

function convexAction<ConvexActionReference extends FunctionReference<"action">>(
  funcRef: ConvexActionReference,
  ...argsOrSkip: ConvexActionArgsOrSkip<ConvexActionReference>
): Pick<
  UseQueryOptions<FunctionReturnType<ConvexActionReference>, ...>,
  "queryKey" | "queryFn" | "staleTime" | "enabled"
>

​
Parameters

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

​
Return value

Returns a partial query options object containing:
​
queryKey
["convexAction", funcRef, args]
A stable, serializable query key for the action call.
​
staleTime
number
Set to Infinity by default. Override this when you want the action result to periodically refetch.
​
enabled
boolean
Only present when args is "skip". Set to false to prevent the action from running.

​
Usage

Basic action query: 
const { data, isPending, error } = useQuery(
  convexAction(api.weather.getSFWeather)
);
With arguments: 
const { data } = useQuery(
  convexAction(api.myModule.myAction, { param: "value" })
);
Conditional / skip: 
const { data } = useQuery(
  convexAction(api.weather.getSFWeather, isEnabled ? {} : "skip")
);
Overriding staleTime for periodic refetch: 
const { data } = useQuery({
  ...convexAction(api.weather.getSFWeather),
  staleTime: 60_000,    // override Infinity; treat data as stale after 1 minute
  refetchInterval: 60_000,
});

Build docs developers (and LLMs) love

Get started for freeTalk to us