Skip to main content

Module: react

Tools to integrate Convex into React applications.

This module contains:

  1. ConvexReactClient, a client for using Convex in React.
  2. ConvexProvider, a component that stores this client in React context.
  3. Hooks for calling into this client within your React components.

Usage

Creating the Client

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

const convex = new ConvexReactClient(convexConfig.origin);

Storing the Client In React Context

import { ConvexProvider } from "convex/react";

<ConvexProvider client={convex}>
<App />
</ConvexProvider>

Generating the Hooks

This module is typically used alongside generated TypeScript hooks.

To generate the hooks, run npx convex codegen in your Convex project. This will create a convex/_generated/react.ts file with the following React hooks, typed for your queries and mutations:

If you aren't using TypeScript and code generation, you can use these untyped hooks instead:

Using the Hooks

import { useQuery, useMutation } from "../convex/_generated/react";

function App() {
const counter = useQuery("getCounter");
const increment = useMutation("incrementCounter");
// Your component here!
}

Interfaces

Classes

Type Aliases

ReactClientOptions

Ƭ ReactClientOptions: Object

Options for ConvexReactClient.

Type declaration

NameTypeDescription
unsavedChangesWarning?booleanWhether to prompt the user that have unsaved changes pending when navigating away or closing a web page with pending Convex mutations. This is only possible when the window object exists, i.e. in a browser. The default value is true.
webSocketConstructor?typeof WebSocketSpecifies an alternate WebSocket constructor to use for client communication with the Convex cloud. The default behavior is to use WebSocket from the global environment.

Functions

useConvexGeneric

useConvexGeneric<API>(): ConvexReactClient<API>

Get the ConvexReactClient within a React component.

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

If you're using TypeScript, use the useConvex function in convex/_generated/react.ts which is typed for your API.

Type parameters

NameType
APIextends GenericAPI

Returns

ConvexReactClient<API>

The active ConvexReactClient object, or undefined.


ConvexProvider

ConvexProvider(props, context?): null | ReactElement<any, any>

Provides an active Convex ConvexReactClient to descendants of this component.

Wrap your app in this component to use Convex hooks useQuery, useMutation, and useConvex.

Parameters

NameTypeDescription
propsPropsWithChildren<{ client: ConvexReactClient<any> ; children?: ReactNode }>an object with a client property that refers to a ConvexReactClient.
context?any-

Returns

null | ReactElement<any, any>


useQueryGeneric

useQueryGeneric<F>(name, ...args): ReturnType<F> | 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.

Throws an error if not used under ConvexProvider.

If you're using TypeScript, use the useQuery function in convex/_generated/react.ts which is typed for your API.

Type parameters

NameType
Fextends (...args: any[]) => any

Parameters

NameTypeDescription
namestringThe name of the query function.
...argsParameters<F>The arguments to the query function.

Returns

ReturnType<F> | undefined

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


useMutationGeneric

useMutationGeneric<API, F>(name): ReactMutation<API, F>

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.

If you're using TypeScript, use the useMutation function imported from convex/_generated/react.ts which is typed for your API.

Throws an error if not used under ConvexProvider.

Type parameters

NameType
APIextends GenericAPI
Fextends (...args: any[]) => Promise<any>

Parameters

NameTypeDescription
namestringThe name of the mutation.

Returns

ReactMutation<API, F>

The ReactMutation object with that name.


makeUseQuery

makeUseQuery<API>(): <Name>(name: Name, ...args: Parameters<NamedQuery<API, Name>>) => undefined | ReturnType<NamedQuery<API, Name>>

Internal method used by Convex code generation.

Type parameters

NameType
APIextends GenericAPI

Returns

fn

▸ <Name>(name, ...args): undefined | ReturnType<NamedQuery<API, Name>>

Type parameters
NameType
Nameextends string | number | symbol
Parameters
NameType
nameName
...argsParameters<NamedQuery<API, Name>>
Returns

undefined | ReturnType<NamedQuery<API, Name>>


makeUseMutation

makeUseMutation<API>(): <K>(name: K) => ReactMutation<API, NamedMutation<API, K>>

Internal method used by Convex code generation.

Type parameters

NameType
APIextends GenericAPI

Returns

fn

▸ <K>(name): ReactMutation<API, NamedMutation<API, K>>

Type parameters
NameType
Kextends string | number | symbol
Parameters
NameType
nameK
Returns

ReactMutation<API, NamedMutation<API, K>>


makeUseConvex

makeUseConvex<API>(): () => ConvexReactClient<API>

Internal method used by Convex code generation.

Type parameters

NameType
APIextends GenericAPI

Returns

fn

▸ (): ConvexReactClient<API>

Returns

ConvexReactClient<API>