Skip to main content

react.ts

This code is generated

These exports are not directly available in the convex package!

Instead you must run npx convex codegen to create convex/_generated/react.ts.

These hooks and types require running code generation because they contain types specific to the query and mutation functions you define for your app.

If you aren't using TypeScript and code generation, you can use the generic versions instead:

React Hooks

useQuery

  • useQuery(name: string, ...args: Value[]): Value | undefined

Load a reactive query within a React component.

This React hook contains internal state that will cause a rerender whenever the query result changes.

This relies on the ConvexProvider being above in the React component tree.

Parameters

NameTypeDescription
namestringThe name of the query function.
...argsValue[]The arguments to the query function.

Returns

Value | undefined

undefined if loading and the query's return value otherwise.


useMutation

  • useMutation(name: string): ReactMutation

Construct a new ReactMutation.

Mutation objects can be called like functions to request execution of the corresponding Convex function, or further configured with optimistic updates.

The value returned by this hook is stable across renders, so it can be used by React dependency arrays and memoization logic relying on object identity without causing rerenders.

This relies on the ConvexProvider being above in the React component tree.

Parameters

NameTypeDescription
namestringThe name of the mutation.

Returns

ReactMutation

The ReactMutation object with that name.


useConvex

  • useConvex()

Get the ConvexReactClient within a React component.

This relies on the ConvexProvider being above in the React component tree.

Returns

ConvexReactClient | undefined

The active ConvexReactClient object, or undefined.

Types

ConvexAPI

Ƭ ConvexAPI: Object

A type describing your app's public Convex API.

This ConvexAPI type includes information about the arguments and return types of your app's query and mutation functions.

This type should be used with type-parameterized classes like ConvexReactClient to create app-specific types.

import { ConvexReactClient } from "convex/react";
import { ConvexAPI } from "../convex/_generated/react";
import convexConfig from "../convex.json";

const convex: ConvexReactClient<ConvexAPI> = new ConvexReactClient(
convexConfig.origin
);

OptimisticLocalStore

A view of the query results currently in the Convex client for use within optimistic updates.

This is an alias of OptimisticLocalStore that is typed for your app's API.