Module: react
Tools to integrate Convex into React applications.
This module contains:
- ConvexReactClient, a client for using Convex in React.
- ConvexProvider, a component that stores this client in React context.
- 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
| Name | Type | Description |
|---|---|---|
unsavedChangesWarning? | boolean | Whether 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 WebSocket | Specifies 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
| Name | Type |
|---|---|
API | extends 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
| Name | Type | Description |
|---|---|---|
props | PropsWithChildren<{ 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
| Name | Type |
|---|---|
F | extends (...args: any[]) => any |
Parameters
| Name | Type | Description |
|---|---|---|
name | string | The name of the query function. |
...args | Parameters<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
| Name | Type |
|---|---|
API | extends GenericAPI |
F | extends (...args: any[]) => Promise<any> |
Parameters
| Name | Type | Description |
|---|---|---|
name | string | The 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
| Name | Type |
|---|---|
API | extends GenericAPI |
Returns
fn
▸ <Name>(name, ...args): undefined | ReturnType<NamedQuery<API, Name>>
Type parameters
| Name | Type |
|---|---|
Name | extends string | number | symbol |
Parameters
| Name | Type |
|---|---|
name | Name |
...args | Parameters<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
| Name | Type |
|---|---|
API | extends GenericAPI |
Returns
fn
▸ <K>(name): ReactMutation<API, NamedMutation<API, K>>
Type parameters
| Name | Type |
|---|---|
K | extends string | number | symbol |
Parameters
| Name | Type |
|---|---|
name | K |
Returns
ReactMutation<API, NamedMutation<API, K>>
makeUseConvex
▸ makeUseConvex<API>(): () => ConvexReactClient<API>
Internal method used by Convex code generation.
Type parameters
| Name | Type |
|---|---|
API | extends GenericAPI |
Returns
fn
▸ (): ConvexReactClient<API>
Returns
ConvexReactClient<API>