@convex-dev/react

@convex-dev/react

React hooks for updating components based on changed in the Convex Cloud. This package is a layer on top of @convex-dev/browser which allows binding to React components. For convenience, it re-exports all of @convex-dev/browser's exports too.

Convex is a platform for building dynamic applications without the complexity of managing a backend or interacting with a database. Data access functions run on the Convex Cloud platform and use the @convex-dev/server libraries to read and manipulate data. This package is used in frontend code to interact with these server-side functions.

See the Convex documentation to get started!

Usage

This library is typically used alongside a more precisely typed client describing the particular Convex functions available to an application, generated by the Convex command line tool. Use alongside a generated client is the preferred way to use this library, but it can also be used directly, which is required for projects which that do not use TypeScript.

To generate a client, run npx convex codegen in any Convex project. A TypeScript module at convex/_generated.ts providing typed versions of three React hooks for communicating with a Convex backend instance will be created or updated.

useQuery()

useQuery takes an initial argument specifying the Convex function to call and passes additional arguments to that Convex function. As a React hook with internal state, every update to the queried value will cause the component where the hook is used to rerender.

This function can be manually created by [makeUserQuery] with a type argument describing an API extending GenericAPI.

useMutation()

useMutation takes a single argument specifying a Convex mutation and returns a Mutation. 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 causes rerenders.

This function can be manually created by [makeUseMutation] with a type argument describing an API extending GenericAPI.

useConvex()

Returns the ConvexReactClient provided by an ancestor ConvexProvider React component.

This function can be manually created by [makeUseConvex] with a type argument describing an API extending GenericAPI.

---

When using this library, useQueryGeneric, useMutationGeneric, and useConvexGeneric provide untyped versions React hooks above.

See Also

• @convex-dev/server is the library used by Convex server functions to interact with data.
• @convex-dev/browser is the layer below this package that provides a framework-independent SDK for data binding to Convex functions.
• @convex-dev/cli is the CLI tool for spinning up Convex backends and syncing functions.