> ## 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()

> Options factory function for subscribing to a reactive Convex query via TanStack Query.

`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

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

<ParamField path="funcRef" type="FunctionReference<'query'>" required>
  The Convex query function reference, imported from `convex/_generated/api`.
</ParamField>

<ParamField path="args" type="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).
</ParamField>

## Return value

Returns a partial query options object containing:

<ResponseField name="queryKey" type="[&#x22;convexQuery&#x22;, funcRef, args]">
  A stable, serializable query key. The `ConvexQueryClient` uses this key to manage WebSocket subscriptions.
</ResponseField>

<ResponseField name="staleTime" type="number">
  Always set to `Infinity`. Convex queries receive live updates via WebSocket, so they never go stale on their own.
</ResponseField>

<ResponseField name="enabled" type="boolean">
  Only present when `args` is `"skip"`. Set to `false` to prevent the query from running.
</ResponseField>

<Note>
  `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.
</Note>

## Usage

**Basic query:**

```tsx theme={null}
const { data } = useQuery(convexQuery(api.messages.list, {}));
```

**Omitting args** (when the function takes no required arguments):

```tsx theme={null}
const { data } = useQuery(convexQuery(api.messages.list));
```

**With arguments:**

```tsx theme={null}
const { data } = useQuery(
  convexQuery(api.messages.search, { query: "hello", limit: 5 })
);
```

**Conditional / skip:**

```tsx theme={null}
const { data } = useQuery(
  convexQuery(api.messages.count, isEnabled ? {} : "skip")
);
```

**With `useSuspenseQuery`:**

```tsx theme={null}
const { data } = useSuspenseQuery(convexQuery(api.messages.list, {}));
```

**Spreading additional options:**

```tsx theme={null}
const { data } = useQuery({
  ...convexQuery(api.messages.list, {}),
  initialData: [],
  gcTime: 10_000,
});
```

<Note>
  Actions cannot be used with `useSuspenseQuery`. Use `convexAction` for Convex actions.
</Note>