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.

To avoid mixing up Convex’s built-in useQuery with TanStack Query’s useQuery, this library re-exports Convex hooks under prefixed names. Import these from @convex-dev/react-query instead of convex/react.

​
useConvexMutation

Re-export of useMutation from convex/react. Returns a mutation function for calling a Convex mutation. Wrap it in TanStack Query’s useMutation to get full mutation state (isPending, isError, onSuccess callbacks, etc.). 
import { useConvexMutation } from "@convex-dev/react-query";
import { useMutation } from "@tanstack/react-query";

const { mutate } = useMutation({
  mutationFn: useConvexMutation(api.messages.send),
});
mutate({ body: "Hello!", author: userId });
Using useConvexMutation inside TanStack Query’s useMutation gives you access to isPending, isError, onSuccess, onError, and other mutation lifecycle callbacks that Convex’s native hook does not provide.

​
useConvexAction

Re-export of useAction from convex/react. Returns a function for calling a Convex action imperatively. Use inside TanStack Query’s useMutation to trigger actions and track their state. 
import { useConvexAction } from "@convex-dev/react-query";
import { useMutation } from "@tanstack/react-query";

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

​
useConvexQuery

Re-export of useQuery from convex/react — Convex’s built-in reactive hook, not TanStack Query’s useQuery. Use this when you want Convex’s native query behavior without TanStack Query integration. 
import { useConvexQuery } from "@convex-dev/react-query";

const messages = useConvexQuery(api.messages.list, {});
For most cases, prefer useQuery(convexQuery(...)) from TanStack Query. It gives you access to TanStack Query’s state management, devtools, and caching features. useConvexQuery is provided for situations where TanStack Query integration is not needed.

​
useConvexQueries

Re-export of useQueries from convex/react. Subscribes to multiple Convex queries at once using Convex’s native hook.

​
useConvexPaginatedQuery

Re-export of usePaginatedQuery from convex/react. Handles cursor-based pagination for Convex paginated query functions. 
import { useConvexPaginatedQuery } from "@convex-dev/react-query";

const { results, status, loadMore } = useConvexPaginatedQuery(
  api.messages.paginated,
  {},
  { initialNumItems: 20 }
);

​
useConvex

Re-export of useConvex from convex/react. Returns the ConvexReactClient instance from the React context. Use this to access the client directly for imperative operations.

​
useConvexAuth

Re-export of useConvexAuth from convex/react. Returns { isLoading, isAuthenticated } from the Convex auth context. 
import { useConvexAuth } from "@convex-dev/react-query";

const { isLoading, isAuthenticated } = useConvexAuth();

​
optimisticallyUpdateValueInPaginatedQuery

Re-export of optimisticallyUpdateValueInPaginatedQuery from convex/react. A utility for optimistically updating items within paginated query results before a mutation completes.
All hooks listed here are imported from @convex-dev/react-query to avoid confusion with TanStack Query hooks of the same name.

Build docs developers (and LLMs) love

Get started for freeTalk to us