Optimistic Updates and Infinite Queries with tRPC
On this page
Why waiting feels slow
When a user ticks a task, the default flow is: send the mutation, wait for the server, invalidate the list, wait again for the refetch, then redraw. On a good connection that's 100 to 300 ms. On a phone on a train it can be seconds, and the checkbox looks broken.
An optimistic update flips the checkbox in the cache immediately, as if the server had already said yes. If the server agrees, nothing visible happens. If it fails, you put the old data back.
The optimistic update pattern
TanStack Query gives you three mutation callbacks that make this safe. With tRPC's typed keys, the cache data is fully typed too:
function TaskList() {
const trpc = useTRPC();
const queryClient = useQueryClient();
const listKey = trpc.task.list.queryKey({});
const tasks = useQuery(trpc.task.list.queryOptions({}));
const toggle = useMutation(trpc.task.toggle.mutationOptions({
onMutate: async ({ id }) => {
// 1. stop any refetch in flight, so it can't overwrite our change
await queryClient.cancelQueries({ queryKey: listKey });
// 2. remember the current data
const previous = queryClient.getQueryData(listKey);
// 3. write the expected result
queryClient.setQueryData(listKey, (old) => old && {
...old,
items: old.items.map((t) => (t.id === id ? { ...t, done: !t.done } : t)),
});
return { previous };
},
// 4. on failure, put the old data back
onError: (_err, _vars, context) => queryClient.setQueryData(listKey, context?.previous),
// 5. either way, refetch to get the server's truth
onSettled: () => queryClient.invalidateQueries({ queryKey: listKey }),
}));
// ... render tasks.data.items, calling toggle.mutate({ id: t.id }) on click
}Each step has a reason:
- Cancel first, or a refetch that started a moment ago could land after your change and undo it on screen.
- Snapshot the data, so you have something to roll back to.
- Write the expected result. Inside
setQueryData,oldis typed as the list's output, so a typo in a field name is a compile error. - Roll back using the snapshot that
onMutatereturned ascontext. - Refetch in
onSettled, which runs after success or failure, so the cache ends up matching the server.
Testing this in a browser with the toggle request forced to fail after 400 ms:
before: [ ] One
optimistic: [x] One (100 ms after the click)
after failure: [ ] One (rolled back)When not to be optimistic
Optimism suits actions that almost always succeed and are easy to undo: ticking a box, starring an item, reordering a list. Avoid it when failure is common or the result is hard to guess:
- payments and orders, where showing "paid" and then taking it back is worse than a short spinner,
- actions the server may reject for business reasons, like booking a slot someone else just took,
- creates where the server assigns important fields, like ids or computed totals.
For creates, a lighter approach often works better: show the new item in a "saving" state using create.isPending and create.variables, without touching the cache, and invalidate on success.
Always tell the user when a rollback happens. A checkbox that silently unticks itself is confusing. A short toast saying "Couldn't save, try again" is enough.
Infinite lists with cursors
For long lists, load a page at a time. tRPC supports TanStack Query's infinite queries for any procedure whose input has a cursor field:
// server
list: protectedProcedure
.input(z.object({
limit: z.number().int().min(1).max(50).default(10),
cursor: z.number().int().nullish(), // supplied by the client per page
}))
.query(({ ctx, input }) => {
const mine = tasksFor(ctx.user.id);
const start = input.cursor ?? 0;
const items = mine.slice(start, start + input.limit);
const nextCursor = start + input.limit < mine.length ? start + input.limit : null;
return { items, nextCursor };
}),On the client, infiniteQueryOptions takes the input *without* the cursor, and you tell it where to find the next one:
function AllTasks() {
const trpc = useTRPC();
const pages = useInfiniteQuery(
trpc.task.list.infiniteQueryOptions(
{ limit: 2 },
{ getNextPageParam: (last) => last.nextCursor },
),
);
const all = pages.data?.pages.flatMap((p) => p.items) ?? [];
return (
<section>
<ol>{all.map((t) => <li key={t.id}>{t.title}</li>)}</ol>
{pages.hasNextPage && (
<button onClick={() => pages.fetchNextPage()} disabled={pages.isFetchingNextPage}>
Load more
</button>
)}
</section>
);
}With five tasks and a page size of two, the browser showed two tasks, then four, then five, and the button disappeared once nextCursor came back as null. tRPC passes the cursor into the input for you.
Infinite queries get their own query key type, "infinite", so trpc.task.list.queryKey() still invalidates them along with normal list queries.
Use keyset cursors in production
The example uses an offset as the cursor, which is simple but has two problems on real data. The database still has to skip all the earlier rows, which gets slow deep in a list. And if a task is added while someone scrolls, offsets shift and they see a duplicate or miss one.
A keyset cursor uses the last item's sort values instead:
cursor: z.object({ createdAt: z.date(), id: z.string() }).nullish(),
// SQL: WHERE (created_at, id) < ($1, $2) ORDER BY created_at DESC, id DESC LIMIT $3Return the last item's { createdAt, id } as nextCursor. The id breaks ties between tasks created at the same moment. With superjson configured, the Date in the cursor survives the trip through the URL.
{ pages: [...], pageParams: [...] }. Update it with the infiniteQueryKey and map over pages, or simply invalidate it and let it refetch.Check yourself
A refetch already in flight could finish after the optimistic write and replace it with old data, so the change would flicker back.
Usually not. Another user may have taken the room, so failures are common and showing a booking that then vanishes is confusing. Show a pending state instead.
A cursor field in its input schema, usually nullish(). You pass the rest of the input to infiniteQueryOptions, and tRPC fills in the cursor for each page from your getNextPageParam. Procedures without a cursor don't offer infiniteQueryOptions at all, so the mistake is caught at compile time.
Feedback. The rollback in onError is correct, but the user should be told it happened, for example with a short toast saying the change couldn't be saved. An unexplained flip back looks like a bug, while a clear message invites them to try again.
The database still has to skip all the earlier rows, which gets slower deeper in the list, and inserts or deletes shift the offsets, so users see duplicates or miss items. A keyset cursor based on the last item's sort values, such as createdAt and id, avoids both problems.