Pagination

Infinite scroll vs. paginated tables. Cursors vs. offsets. Convex pagination patterns.

Two pagination styles in most apps:

Infinite scroll

For feeds — chat, social, activity. User scrolls; new items load. Best for chronological browsing.

Paginated table

For data tables — admin panels, reports. User clicks Next/Prev. Best for known size and exact navigation.

Convex pagination

Convex provides cursor-based pagination via paginate:

convex/tasks.ts

import { paginationOptsValidator } from "convex/server";

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

Returns:

{ page: TaskRow[], isDone: boolean, continueCursor: string }

Client — infinite scroll

import { usePaginatedQuery } from "convex/react";

const { results, status, loadMore } = usePaginatedQuery(
  api.tasks.listPaginated,
  { teamId },
  { initialNumItems: 25 }
);

return (
  <>
    {results.map(t => <TaskRow key={t._id} task={t} />)}
    {status === "CanLoadMore" && (
      <button onClick={() => loadMore(25)}>Load more</button>
    )}
  </>
);

For auto-loading on scroll, attach an Intersection Observer to a sentinel element and call loadMore when it enters the viewport.

Client — paginated table

Maintain page state in URL:

const page = parseInt(searchParams.get("page") ?? "1");
const { results } = usePaginatedQuery(
  api.tasks.listPaginated,
  { teamId },
  { initialNumItems: 25 * page }
);
const items = results.slice((page - 1) * 25, page * 25);

For more efficient page jumps (skip to page 5 without loading 1–4), use offset-based pagination — Convex doesn’t have native offset pagination; you can implement via _creationTime cursors plus client-side offset.

Tips

Pick a sane initialNumItems. 25 is a good default; smaller wastes round trips, larger wastes bandwidth.

For truly large data, prefer search over pagination. Users rarely scroll past page 3 — give them a search bar instead.

Related

Convex queries

The query layer.

Search patterns

Search as an alternative to pagination.

Performance issues

Pagination as a fix.