name: convex-realtime description: Builds reactive UIs on Convex subscriptions: useQuery patterns, optimistic updates, pagination that stays live, presence, and avoiding subscription churn. Use when wiring the frontend to Convex, when data does not update live, or when a page rerenders too much.

Convex realtime

Every useQuery is a live subscription. The one rule: keep the set of documents a query reads small and indexed, because that read set decides when the query reruns.

When to reach for this

• Wiring a React component to Convex for the first time
• Data changes on the server but the page does not update
• A list or dashboard rerenders on every unrelated write
• A "load more" list drops or duplicates rows when new data lands
• Showing who is online or typing

How subscriptions work

useQuery opens a subscription over the client's websocket. The server runs the query, records its read set (every document and index range it touched), and pushes the result. When a mutation commits a write that overlaps that read set, the server reruns the query and pushes the new result. Nothing overlaps, nothing reruns. Results are cached per function and args, so two components calling useQuery(api.tasks.list, { userId }) share one subscription. All active subscriptions update together at the same database timestamp, so the UI never shows a half applied mutation. Queries must be deterministic for this to hold, which is why Date.now(), Math.random(), and fetch are not allowed inside them.