> ## 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.

# 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.

```tsx theme={null}
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 });
```

<Tip>
  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.
</Tip>

## Actions as mutations

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

```tsx theme={null}
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.

```tsx theme={null}
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>;
}
```

<Warning>
  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.
</Warning>

## Skipping actions conditionally

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

```tsx theme={null}
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:

```tsx theme={null}
import { ConvexProvider } from "convex/react";

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