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";

// typically loaded from an environment variable
const address = "https://small-mouse-123.convex.cloud"
const convex = new ConvexReactClient(address);

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 hooks.

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

If you aren't using 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​

AuthTokenFetcher​

Ƭ AuthTokenFetcher: () => Promise<string | null | undefined>

Type declaration​

▸ (): Promise<string | null | undefined>

An async function returning the JWT-encoded OpenID Connect Identity Token if available. See setAuth.

Returns​

Promise<string | null | undefined>

UseQueryForAPI​

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

Type parameters​

NameType
APIextends GenericAPI

Type declaration​

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

Internal type helper used by Convex code generation.

Used to give useQueryGeneric a type specific to your API.

Type parameters​
NameType
Nameextends QueryNames<API>
Parameters​
NameType
nameName
...argsParameters<NamedQuery<API, Name>>
Returns​

ReturnType<NamedQuery<API, Name>> | undefined

UseMutationForAPI​

Ƭ UseMutationForAPI<API>: <Name>(name: Name) => ReactMutation<API, Name>

Type parameters​

NameType
APIextends GenericAPI

Type declaration​

▸ <Name>(name): ReactMutation<API, Name>

Internal type helper used by Convex code generation.

Used to give useMutationGeneric a type specific to your API.

Type parameters​
NameType
Nameextends MutationNames<API>
Parameters​
NameType
nameName
Returns​

ReactMutation<API, Name>

UseActionForAPI​

Ƭ UseActionForAPI<API>: <Name>(name: Name) => ReactAction<API, Name>

Type parameters​

NameType
APIextends GenericAPI

Type declaration​

▸ <Name>(name): ReactAction<API, Name>

Internal type helper used by Convex code generation.

Used to give useMutationGeneric a type specific to your API.

Type parameters​
NameType
Nameextends ActionNames<API>
Parameters​
NameType
nameName
Returns​

ReactAction<API, Name>

UseConvexForAPI​

Ƭ UseConvexForAPI<API>: () => ConvexReactClient<API>

Type parameters​

NameType
APIextends GenericAPI

Type declaration​

▸ (): ConvexReactClient<API>

Internal type helper used by Convex code generation.

Used to give useConvexGeneric a type specific to your API.

Returns​

ConvexReactClient<API>

UsePaginatedQueryResult​

Ƭ UsePaginatedQueryResult<T>: { results: T[] } & { status: "CanLoadMore" ; loadMore: (numItems: number) => void } | { status: "LoadingMore" ; loadMore: undefined } | { status: "Exhausted" ; loadMore: undefined }

The result of calling the usePaginatedQueryGeneric hook.

This includes:

  1. results - An array of the currently loaded results.
  2. status - The status of the pagination. The possible statuses are:
  • "CanLoadMore": This query may have more items to fetch. Call loadMore to fetch another page.
  • "LoadingMore": We're currently loading another page of results.
  • "Exhausted": We've paginated to the end of the list.
  1. loadMore A callback to fetch more results. This will be undefined unless the status is "CanLoadMore".

Type parameters​

Name
T

PaginatedQueryFunction​

Ƭ PaginatedQueryFunction<Args, ReturnType>: (paginationOptions: PaginationOptions, ...args: Args) => PaginationResult<ReturnType>

Type parameters​

NameType
Argsextends any[]
ReturnTypeReturnType

Type declaration​

▸ (paginationOptions, ...args): PaginationResult<ReturnType>

A query function that is usable with usePaginatedQueryGeneric.

The function's first argument must be a PaginationOptions object. The function must return a PaginationResult.

Parameters​
NameType
paginationOptionsPaginationOptions
...argsArgs
Returns​

PaginationResult<ReturnType>

PaginatedQueryNames​

Ƭ PaginatedQueryNames<API>: keyof PickByValue<API["queries"], PaginatedQueryFunction<any, any>> & string

The names of the paginated query functions in a Convex API.

These are normal query functions that match PaginatedQueryFunction.

Type parameters​

NameType
APIextends GenericAPI

PaginatedQueryArgs​

Ƭ PaginatedQueryArgs<Query>: Query extends PaginatedQueryFunction<infer Args, any> ? Args : never

The type of the arguments to a PaginatedQueryFunction.

This type includes all the arguments after the initial PaginationOptions argument.

Type parameters​

NameType
Queryextends PaginatedQueryFunction<any, any>

PaginatedQueryReturnType​

Ƭ PaginatedQueryReturnType<Query>: Query extends PaginatedQueryFunction<any, infer ReturnType> ? ReturnType : never

The return type of a PaginatedQueryFunction.

This is the type of the inner document or object within the PaginationResult that a paginated query function returns.

Type parameters​

NameType
Queryextends PaginatedQueryFunction<any, any>

UsePaginatedQueryForAPI​

Ƭ UsePaginatedQueryForAPI<API>: <Name>(name: Name, options: { initialNumItems: number }, ...args: PaginatedQueryArgs<NamedQuery<API, Name>>) => UsePaginatedQueryResult<PaginatedQueryReturnType<NamedQuery<API, Name>>>

Type parameters​

NameType
APIextends GenericAPI

Type declaration​

▸ <Name>(name, options, ...args): UsePaginatedQueryResult<PaginatedQueryReturnType<NamedQuery<API, Name>>>

Internal type helper used by Convex code generation.

Used to give usePaginatedQueryGeneric a type specific to your API.

Type parameters​
NameType
Nameextends PaginatedQueryNames<API>
Parameters​
NameType
nameName
optionsObject
options.initialNumItemsnumber
...argsPaginatedQueryArgs<NamedQuery<API, Name>>
Returns​

UsePaginatedQueryResult<PaginatedQueryReturnType<NamedQuery<API, Name>>>

RequestForQueries​

Ƭ RequestForQueries: Record<string, { name: string ; args: Value[] }>

An object representing a request to load multiple queries.

The keys of this object are identifiers and the values are objects containing the name of the query function and the arguments to pass to it.

This is used as an argument to useQueriesGeneric.

UseQueriesForAPI​

Ƭ UseQueriesForAPI<API>: <QueryNameMap>(queries: { [Identifier in keyof QueryNameMap]: Object }) => { [Identifier in keyof QueryNameMap]: ReturnType<NamedQuery<API, QueryNameMap[Identifier]>> | undefined | Error }

Type parameters​

NameType
APIextends GenericAPI

Type declaration​

▸ <QueryNameMap>(queries): { [Identifier in keyof QueryNameMap]: ReturnType<NamedQuery<API, QueryNameMap[Identifier]>> | undefined | Error }

Internal type helper used by Convex code generation.

Used to give useQueriesGeneric a type specific to your API.

Type parameters​
NameType
QueryNameMapextends Record<string, QueryNames<API>>
Parameters​
NameType
queries{ [Identifier in keyof QueryNameMap]: Object }
Returns​

{ [Identifier in keyof QueryNameMap]: ReturnType<NamedQuery<API, QueryNameMap[Identifier]>> | undefined | Error }

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 code generation, use the useConvex function in convex/_generated/react.js 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<API, Name>(name, ...args): ReturnType<NamedQuery<API, Name>> | 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 code generation, use the useQuery function in convex/_generated/react.js which is typed for your API.

Type parameters​

NameType
APIextends GenericAPI
Nameextends string

Parameters​

NameTypeDescription
nameNameThe name of the query function.
...argsParameters<NamedQuery<API, Name>>The arguments to the query function.

Returns​

ReturnType<NamedQuery<API, Name>> | undefined

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

useMutationGeneric​

▸ useMutationGeneric<API, Name>(name): ReactMutation<API, Name>

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 code generation, use the useMutation function in convex/_generated/react.js which is typed for your API.

Throws an error if not used under ConvexProvider.

Type parameters​

NameType
APIextends GenericAPI
Nameextends string

Parameters​

NameTypeDescription
nameNameThe name of the mutation.

Returns​

ReactMutation<API, Name>

The ReactMutation object with that name.

useActionGeneric​

▸ useActionGeneric<API, Name>(name): ReactAction<API, Name>

Construct a new ReactAction.

Action objects can be called like functions to request execution of the corresponding Convex function.

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 code generation, use the useAction function in convex/_generated/react.js which is typed for your API.

Throws an error if not used under ConvexProvider.

Type parameters​

NameType
APIextends GenericAPI
Nameextends string

Parameters​

NameTypeDescription
nameNameThe name of the action.

Returns​

ReactAction<API, Name>

The ReactAction object with that name.

usePaginatedQueryGeneric​

▸ usePaginatedQueryGeneric(name, options, ...args): UsePaginatedQueryResult<any>

Load data reactively from a paginated query to a create a growing list.

This can be used to power "infinite scroll" UIs.

This hook must be used with Convex query functions that match PaginatedQueryFunction. This means they must:

  1. Have a first argument must be an object containing numItems and cursor.
  2. Return a PaginationResult.

usePaginatedQueryGeneric concatenates all the pages of results into a single list and manages the continuation cursors when requesting more items.

Example usage:

const { results, status, loadMore } = usePaginatedQueryGeneric(
  "listMessages",
  { initialNumItems: 5 },
  "#general"
);

If the query name or args change, the pagination state will be reset to the first page. Similarly, if any of the pages result in an InvalidCursor or QueryScannedTooManyDocuments error, the pagination state will also reset to the first page.

To learn more about pagination, see Paginated Queries.

If you're using code generation, use the usePaginatedQuery function in convex/_generated/react.js which is typed for your API.

Parameters​

NameTypeDescription
namestringThe name of the query function.
optionsObjectAn object specifying the initialNumItems to be loaded in the first page.
options.initialNumItemsnumber-
...argsValue[]The arguments to the query function, excluding the first.

Returns​

UsePaginatedQueryResult<any>

A UsePaginatedQueryResult that includes the currently loaded items, the status of the pagination, and a loadMore function.

optimisticallyUpdateValueInPaginatedQuery​

▸ optimisticallyUpdateValueInPaginatedQuery<API, Name>(localStore, name, args, updateValue): void

Optimistically update the values in a paginated list.

This optimistic update is designed to be used to update data loaded with usePaginatedQueryGeneric. It updates the list by applying updateValue to each element of the list across all of the loaded pages.

This will only apply to queries with a matching names and arguments.

Example usage:

const myMutation = useMutation("myMutationName")
.withOptimisticUpdate((localStore, mutationArg) => {

  // Optimistically update the document with ID `mutationArg`
  // to have an additional property.

  optimisticallyUpdateValueInPaginatedQuery(
    localStore,
    "paginatedQueryName",
    [],
    currentValue => {
      if (mutationArg.equals(currentValue._id)) {
        return {
          ...currentValue,
          "newProperty": "newValue",
        };
      }
      return currentValue;
    }
  );

});

Type parameters​

NameType
APIextends GenericAPI
Nameextends string

Parameters​

NameTypeDescription
localStoreOptimisticLocalStore<API>-
nameNameThe name of the paginated query function.
argsPaginatedQueryArgs<NamedQuery<API, Name>>The arguments to the query function, excluding the first.
updateValue(currentValue: PaginatedQueryReturnType<NamedQuery<API, Name>>) => PaginatedQueryReturnType<NamedQuery<API, Name>>A function to produce the new values.

Returns​

void

useQueriesGeneric​

▸ useQueriesGeneric(queries): Record<string, any | undefined | Error>

Load a variable number of reactive Convex queries.

useQueriesGeneric is similar to useQueryGeneric but it allows loading multiple queries which can be useful for loading a dynamic number of queries without violating the rules of React hooks.

This hook accepts an object whose keys are identifiers for each query and the values are objects of { name: string, args: Value[] }. The name is the name of the Convex query function to load, and the args are the arguments to that function.

The hook returns an object that maps each identifier to the result of the query, undefined if the query is still loading, or an instance of Error if the query threw an exception.

For example if you loaded a query like:

const results = useQueriesGeneric({
  messagesInGeneral: {
    name: "listMessages",
    args: ["#general"]
  }
});

then the result would look like:

{
  messagesInGeneral: [{
    channel: "#general",
    body: "hello"
    _id: ...,
    _creationTime: ...
  }]
}

This React hook contains internal state that will cause a rerender whenever any of the query results change.

Throws an error if not used under ConvexProvider.

If you're using code generation, use the useQueries function in convex/_generated/react.js which is typed for your API.

Parameters​

NameTypeDescription
queriesRequestForQueriesAn object mapping identifiers to objects of {name: string, args: Value[] } describing which query functions to fetch.

Returns​

Record<string, any | undefined | Error>

An object with the same keys as the input. The values are the result of the query function, undefined if it's still loading, or an Error if it threw an exception.