React

@confect/react provides drop-in replacements for Convex’s React hooks. Each hook automatically encodes your args and decodes return values through the Effect Schemas defined in your function specs. You work with the Schema Type (decoded) values on both sides—the hooks handle the round-trip to Convex’s Encoded representation transparently. Functions are referenced via refs (from confect/_generated/refs) instead of Convex’s api object. Each ref carries the args, returns, and (optionally) error schemas from the corresponding function spec, which is what enables the automatic encoding and decoding.

Setup

The React provider setup is the same as vanilla Convex.

src/main.tsx

import { ConvexProvider, ConvexReactClient } from "convex/react";
import React from "react";
import ReactDOM from "react-dom/client";

import App from "./App";

const convexClient = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
    <ConvexProvider client={convexClient}>
      <App />
    </ConvexProvider>
  </React.StrictMode>,
);

`useQuery`

Encodes args using the spec’s args schema, passes them to Convex, and decodes the result using the spec’s returns schema. Returns a QueryResult<A, E>—a tagged union with Loading, Success, and Failure variants. Given this spec:

confect/notes.spec.ts

import { FunctionSpec, GroupSpec } from "@confect/core";
import * as Schema from "effect/Schema";

import notes from "./_generated/tables/notes";

export default GroupSpec.make().addFunction(
  FunctionSpec.publicQuery({
    name: "list",
    returns: () => Schema.Array(notes.Doc),
  }),
);

The hook accepts {} (the Type of Schema.Struct({})) as args and returns a QueryResult<readonly notes.Doc["Type"][]>. Match it with QueryResult.match:

import { QueryResult, useQuery } from "@confect/react";
import refs from "../confect/_generated/refs";

const NoteList = () => {
  const notes = useQuery(refs.public.notes.list, {});

  return QueryResult.match(notes, {
    onLoading: () => <p>Loading…</p>,
    onSuccess: (notes) => (
      <ul>
        {notes.map((note) => (
          <li key={note._id}>{note.text}</li>
        ))}
      </ul>
    ),
  });
};

QueryResult also exposes the lower-level predicates QueryResult.isLoading, QueryResult.isSuccess, and QueryResult.isFailure for cases where pattern matching is awkward.

Typed errors

When the ref’s spec declares an error schema, useQuery returns QueryResult<A, E> and QueryResult.match requires an onFailure handler that receives the decoded typed error. See Error Handling for how to declare error schemas.

import { QueryResult, useQuery } from "@confect/react";
import refs from "../confect/_generated/refs";

const NoteLookup = ({ noteId }: { noteId: string }) => {
  const lookup = useQuery(refs.public.notes.getOrFail, { noteId });

  return (
    <div>
      {QueryResult.match(lookup, {
        onLoading: () => "Looking up…",
        onSuccess: (note) => `Found: ${note.text}`,
        onFailure: (error) => `Note ${error.noteId} not found.`,
      })}
    </div>
  );
};

Failures that are not declared in the error schema are not surfaced as Failure. They propagate the same way they do with convex/react’s useQuery (typically reaching the nearest error boundary).

Skipping queries

Pass "skip" instead of args to disable the query subscription. The hook returns a Loading variant whose skipped flag is true, which lets you distinguish a query that is genuinely in flight from one sitting idle because no args have been provided.

import { QueryResult, useQuery } from "@confect/react";
import refs from "../confect/_generated/refs";

const NoteDetail = ({ selectedId }: { selectedId: string | undefined }) => {
  const note = useQuery(
    refs.public.notes.get,
    selectedId !== undefined ? { id: selectedId } : "skip",
  );

  return QueryResult.match(note, {
    onLoading: (skipped) => <p>{skipped ? "Select a note" : "Loading…"}</p>,
    onSuccess: (note) => <p>{note.text}</p>,
  });
};

`usePaginatedQuery`

Loads data reactively from a paginated query, mirroring the ergonomics of usePaginatedQuery from convex/react. The ref must come from a spec defined with FunctionSpec.publicPaginatedQuery—passing any other ref fails at runtime with an error pointing at the constructor. Args are encoded using the spec’s user-args schema (paginationOpts is managed by the hook, not the caller), and each loaded page is decoded using the spec’s item schema. Pass "skip" instead of args to disable the query, like useQuery. Returns a PaginatedQueryResult<Item, E>. The loaded variants—LoadingFirstPage, LoadingMore, CanLoadMore, and Exhausted—all carry results and isLoading, and CanLoadMore additionally carries loadMore, so the common UI needs only field access and a couple of predicates:

import { PaginatedQueryResult, usePaginatedQuery } from "@confect/react";
import refs from "../confect/_generated/refs";

const PaginatedNoteList = () => {
  const notes = usePaginatedQuery(
    refs.public.notes.listByAuthor,
    { author: "ada" },
    { initialNumItems: 10 },
  );

  return (
    <div>
      <ul>
        {notes.results.map((note) => (
          <li key={note._id}>{note.text}</li>
        ))}
      </ul>
      {notes.isLoading && <p>Loading…</p>}
      {PaginatedQueryResult.isCanLoadMore(notes) && (
        <button type="button" onClick={() => notes.loadMore(10)}>
          Load more
        </button>
      )}
    </div>
  );
};

loadMore lives only on CanLoadMore, the one state it can make progress from—the underlying Convex hook exposes it on every status, but calling it while a page is in flight, once the list is exhausted, or after a failure is an intentional no-op there. Narrowing with isCanLoadMore (or match’s onCanLoadMore) makes that statically apparent instead of silently dropping the call. PaginatedQueryResult also provides match for exhaustive pattern matching, and the predicates isLoadingFirstPage, isLoadingMore, isExhausted, isLoading, and isFailure.

Typed errors

When the spec declares an error schema, the result type gains a Failure variant carrying the decoded typed error—errors are values, consistent with useQuery. Narrow with PaginatedQueryResult.isFailure (or handle onFailure in match) to reach it:

const notes = usePaginatedQuery(
  refs.public.notes.listOrFail,
  {},
  { initialNumItems: 10 },
);

if (PaginatedQueryResult.isFailure(notes)) {
  // `results` holds the pages loaded before the failure, so they can still
  // be rendered alongside the error.
  return (
    <div>
      <NoteList notes={notes.results} />
      <p>Failed to load more: {notes.error.reason}</p>
    </div>
  );
}
// notes: narrowed to the non-`Failure` variants—isLoading is available too.

Every variant carries results, Failure included: when a later page fails, the pages already loaded are not discarded. Without an error schema, the Failure variant is excluded from the type entirely, so no narrowing is needed. Failures not declared in the error schema are thrown during render and propagate to the nearest error boundary.

usePaginatedQuery requires convex 1.36.0 or newer.

`useStreamPaginatedQuery`

Loads data reactively from a paginated query whose handler paginates a query stream with QueryStream.paginate. Those pages are not tracked by Convex’s query journal, which usePaginatedQuery relies on to keep pages consistent as data changes, so this hook maintains that guarantee itself: every loaded page is pinned to a fixed index range by echoing its continueCursor back as the next subscription’s endCursor. Adjacent pages always meet exactly, a document is never shown twice or lost between pages, and a page that outgrows initialNumItems is split in two. The call shape and the result are the same as usePaginatedQuery: args are encoded with the spec’s user-args schema, pages are decoded with its item schema, "skip" disables the query, and the result is a PaginatedQueryResult<Item, E> with a Failure variant when the spec declares an error schema.

import { PaginatedQueryResult, useStreamPaginatedQuery } from "@confect/react";
import refs from "../confect/_generated/refs";

const Feed = () => {
  const feed = useStreamPaginatedQuery(
    refs.public.notes.feed,
    {},
    { initialNumItems: 10 },
  );

  return (
    <div>
      <ul>
        {feed.results.map((note) => (
          <li key={note._id}>{note.text}</li>
        ))}
      </ul>
      {feed.isLoading && <p>Loading…</p>}
      {PaginatedQueryResult.isCanLoadMore(feed) && (
        <button type="button" onClick={() => feed.loadMore(10)}>
          Load more
        </button>
      )}
    </div>
  );
};

The options also accept maximumRowsRead and maximumBytesRead, per-page read budgets forwarded to the server. On a stream that filters out most of what it reads, a page that would otherwise scan past Convex’s query limits returns truncated with SplitRequired instead, and the hook splits it. When the server fails a page with paginationError: "InvalidCursor", the hook restarts pagination from the first page rather than failing. Stream queries emit this signal for malformed cursors, unsupported cursor versions, or mismatched runtime key-field layouts—not every change to query semantics. See Cursor format and validation.

useStreamPaginatedQuery also works with paginated queries that use the built-in paginate, since it only relies on the endCursor protocol field. It subscribes to one query per loaded page.

`useMutation`

Returns a function that encodes args using the spec’s args schema, calls the Convex mutation, and decodes the result using the spec’s returns schema. The returned promise’s shape depends on whether the spec declares an error schema.

Without an `error` schema

The function returns Promise<A>, matching convex/react’s useMutation. Undeclared failures still reject the promise.

confect/notes.spec.ts

import { Id } from "./_generated/id";

FunctionSpec.publicMutation({
  name: "insert",
  args: () => ({ text: Schema.String }),
  returns: () => Id("notes"),
});

import { useMutation } from "@confect/react";
import refs from "../confect/_generated/refs";

const InsertNote = () => {
  const insertNote = useMutation(refs.public.notes.insert);

  return (
    <button onClick={() => void insertNote({ text: "Hello" })}>
      Insert note
    </button>
  );
};

With an `error` schema

When the spec declares an error schema, the function returns Promise<Result<A, E>>. Unwrap with Result.match (or another Result combinator) to handle both branches. Undeclared failures still reject the promise.

confect/notes.spec.ts

import { Id } from "./_generated/id";

FunctionSpec.publicMutation({
  name: "deleteOrFail",
  args: () => ({ noteId: Id("notes") }),
  returns: () => Schema.Null,
  error: () => Schema.Union([NoteNotFound, Forbidden]),
});

import { useMutation } from "@confect/react";
import * as Result from "effect/Result";
import refs from "../confect/_generated/refs";

const DeleteNote = ({ noteId }: { noteId: string }) => {
  const deleteOrFail = useMutation(refs.public.notes.deleteOrFail);

  const handleClick = async () => {
    const result = await deleteOrFail({ noteId });
    Result.match(result, {
      onFailure: (error) => console.error(error._tag, error),
      onSuccess: () => console.log("deleted"),
    });
  };

  return <button onClick={handleClick}>Delete</button>;
};

`useAction`

Same shape as useMutation: returns Promise<A> when the ref has no error schema, and Promise<Result<A, E>> when it does.

confect/random.spec.ts

FunctionSpec.publicAction({
  name: "getNumber",
  returns: () => Schema.Number,
});

import { useAction } from "@confect/react";
import refs from "../confect/_generated/refs";

const RandomNumber = () => {
  const getRandom = useAction(refs.public.random.getNumber);

  const handleClick = () => {
    void getRandom({}).then(console.log);
  };

  return <button onClick={handleClick}>Get random</button>;
};

Differences from vanilla Convex hooks

Vanilla Convex	Confect
Functions referenced via `api.module.fn`	Functions referenced via `refs`
Args passed directly to Convex as-is	Args are schema-encoded from `Type` to `Encoded` before sending to Convex
Return values received directly from Convex as-is	Return values are schema-decoded from `Encoded` to `Type` before returning
`useQuery` returns `T \| undefined`	`useQuery` returns `QueryResult<A, E>`
Cannot distinguish loading from skipped	`Loading` carries a `skipped: boolean` flag
`useMutation`/`useAction` always return `Promise<T>`	Refs with an `error` schema return `Promise<Result<A, E>>`; refs without one still return `Promise<A>`
`usePaginatedQuery` throws query errors during render	`usePaginatedQuery` returns `PaginatedQueryResult<Item, E>` with declared errors as a `Failure` variant
Pass `"skip"` to disable query subscription	Same—pass `"skip"` to disable query subscription

Getting Started

Concepts

Server

Clients

Guides

Setup

`useQuery`

Typed errors

Skipping queries

`usePaginatedQuery`

Typed errors

`useStreamPaginatedQuery`

`useMutation`

Without an `error` schema

With an `error` schema

`useAction`

Differences from vanilla Convex hooks

​Setup

​useQuery

​Typed errors

​Skipping queries

​usePaginatedQuery

​Typed errors

​useStreamPaginatedQuery

​useMutation

​Without an error schema

​With an error schema

​useAction

​Differences from vanilla Convex hooks

Setup

`useQuery`

Typed errors

Skipping queries

`usePaginatedQuery`

Typed errors

`useStreamPaginatedQuery`

`useMutation`

Without an `error` schema

With an `error` schema

`useAction`

Differences from vanilla Convex hooks