Convex Realtime

Build reactive applications with Convex's real-time subscriptions, optimistic updates, intelligent caching, and cursor-based pagination.

Documentation Sources

Before implementing, do not assume; fetch the latest documentation:

Primary: https://docs.convex.dev/client/react Optimistic Updates: https://docs.convex.dev/client/react/optimistic-updates Pagination: https://docs.convex.dev/database/pagination For broader context: https://docs.convex.dev/llms.txt Instructions How Convex Realtime Works Automatic Subscriptions - useQuery creates a subscription that updates automatically Smart Caching - Query results are cached and shared across components Consistency - All subscriptions see a consistent view of the database Efficient Updates - Only re-renders when relevant data changes Basic Subscriptions // React component with real-time data import { useQuery } from "convex/react"; import { api } from "../convex/_generated/api";

function TaskList({ userId }: { userId: Id<"users"> }) { // Automatically subscribes and updates in real-time const tasks = useQuery(api.tasks.list, { userId });

if (tasks === undefined) { return

return (

{tasks.map((task) => (
• {task.title}
))}

Conditional Queries import { useQuery } from "convex/react"; import { api } from "../convex/_generated/api";

function UserProfile({ userId }: { userId: Id<"users"> | null }) { // Skip query when userId is null const user = useQuery( api.users.get, userId ? { userId } : "skip" );

if (userId === null) { return

if (user === undefined) { return

return

Mutations with Real-time Updates import { useMutation, useQuery } from "convex/react"; import { api } from "../convex/_generated/api";

function TaskManager({ userId }: { userId: Id<"users"> }) { const tasks = useQuery(api.tasks.list, { userId }); const createTask = useMutation(api.tasks.create); const toggleTask = useMutation(api.tasks.toggle);

const handleCreate = async (title: string) => { // Mutation triggers automatic re-render when data changes await createTask({ title, userId }); };

const handleToggle = async (taskId: Id<"tasks">) => { await toggleTask({ taskId }); };

return (

Optimistic Updates

Show changes immediately before server confirmation:

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

function TaskItem({ task }: { task: Task }) { const toggleTask = useMutation(api.tasks.toggle).withOptimisticUpdate( (localStore, args) => { const { taskId } = args; const currentValue = localStore.getQuery(api.tasks.get, { taskId });

  if (currentValue !== undefined) {
    localStore.setQuery(api.tasks.get, { taskId }, {
      ...currentValue,
      completed: !currentValue.completed,
    });
  }
}

);

return (

Optimistic Updates for Lists import { useMutation } from "convex/react"; import { api } from "../convex/_generated/api";

function useCreateTask(userId: Id<"users">) { return useMutation(api.tasks.create).withOptimisticUpdate( (localStore, args) => { const { title, userId } = args; const currentTasks = localStore.getQuery(api.tasks.list, { userId });

  if (currentTasks !== undefined) {
    // Add optimistic task to the list
    const optimisticTask = {
      _id: crypto.randomUUID() as Id<"tasks">,
      _creationTime: Date.now(),
      title,
      userId,
      completed: false,
    };

    localStore.setQuery(api.tasks.list, { userId }, [
      optimisticTask,
      ...currentTasks,
    ]);
  }
}

); }

Cursor-Based Pagination // convex/messages.ts import { query } from "./_generated/server"; import { v } from "convex/values"; import { paginationOptsValidator } from "convex/server";

export const listPaginated = query({ args: { channelId: v.id("channels"), paginationOpts: paginationOptsValidator, }, handler: async (ctx, args) => { return await ctx.db .query("messages") .withIndex("by_channel", (q) => q.eq("channelId", args.channelId)) .order("desc") .paginate(args.paginationOpts); }, });

// React component with pagination import { usePaginatedQuery } from "convex/react"; import { api } from "../convex/_generated/api";

function MessageList({ channelId }: { channelId: Id<"channels"> }) { const { results, status, loadMore } = usePaginatedQuery( api.messages.listPaginated, { channelId }, { initialNumItems: 20 } );

return (

  {status === "CanLoadMore" && (
    <button onClick={() => loadMore(20)}>Load More</button>
  )}

  {status === "LoadingMore" && <div>Loading...</div>}

  {status === "Exhausted" && <div>No more messages</div>}
</div>

observerRef.current = new IntersectionObserver((entries) => {
  if (entries[0].isIntersecting && status === "CanLoadMore") {
    loadMore(20);
  }
});

if (loadMoreRef.current) {
  observerRef.current.observe(loadMoreRef.current);
}

return () => observerRef.current?.disconnect();

// Enrich with author names
return Promise.all(
  messages.map(async (msg) => {
    const author = await ctx.db.get(msg.authorId);
    return {
      ...msg,
      authorName: author?.name ?? "Unknown",
    };
  })
);

await sendMessage({
  channelId,
  authorId: userId,
  content: input.trim(),
});
setInput("");

  <form onSubmit={handleSend}>
    <input
      value={input}
      onChange={(e) => setInput(e.target.value)}
      placeholder="Type a message..."
    />
    <button type="submit">Send</button>
  </form>
</div>