Mutations and actions

Use Convex mutations and actions with TanStack Query’s useMutation hook.

@convex-dev/react-query re-exports useConvexMutation and useConvexAction from convex/react so you can use them as mutationFn values inside TanStack Query’s useMutation hook.

Mutations

useConvexMutation returns a function you can pass directly to useMutation. Call mutate with the arguments for your Convex mutation function.

import { useMutation } from "@tanstack/react-query";
import { useConvexMutation } from "@convex-dev/react-query";
import { api } from "../convex/_generated/api";

const { mutate, isPending } = useMutation({
  mutationFn: useConvexMutation(api.messages.send),
});

// Call mutate with the function args
mutate({ body: "Hello!", author: userId });

There is no need to call queryClient.invalidateQueries() after a mutation. Convex pushes updated query results to all active subscriptions automatically, so your UI stays consistent without any manual cache management.

Actions as mutations

Actions that modify data or trigger side effects can be wrapped in useMutation the same way.

const { mutate } = useMutation({
  mutationFn: useConvexAction(api.time.getTotal),
});

Actions as queries (non-reactive)

Use convexAction with useQuery to call a Convex action and display its result. Unlike convexQuery, the result is not a live subscription.

import { useQuery } from "@tanstack/react-query";
import { convexAction } from "@convex-dev/react-query";

function Weather() {
  const { data, isPending, error } = useQuery(
    convexAction(api.weather.getSFWeather)
  );
  if (isPending || error) return <span>Loading...</span>;
  return <div>It is {data.fahrenheit}°F in San Francisco</div>;
}

Convex actions are not reactive. They follow normal TanStack Query refetch semantics — refetch on window focus, stale time, manual invalidation, etc. They do not receive pushed updates from the server.

Skipping actions conditionally

Pass "skip" as the second argument to convexAction to disable the query conditionally. enabled: false is set automatically.

const { data } = useQuery(
  convexAction(api.weather.getSFWeather, "skip")
);

ConvexProvider for hooks

useConvexMutation and useConvexAction are React hooks from convex/react and require a ConvexProvider in the component tree. If you’re using ConvexAuthProvider or ConvexProviderWithClerk, these already serve as the required provider.

If you’re using a plain setup without an auth provider, wrap your app explicitly:

import { ConvexProvider } from "convex/react";

<ConvexProvider client={convexClient}>
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>
</ConvexProvider>