How to use a useSuspenceQuery with a paginated query?

[uneven charm]

Below is the established pattern

export const Route = createFileRoute('/posts')({
  loader: async (opts) => {
    await opts.context.queryClient.ensureQueryData(
      convexQuery(api.messages.list, {}),
    );
  };
  component: () => {
    const { data } = useSuspenseQuery(convexQuery(api.messages.list, {}));
    return (
      <div>
    {data.map((message) => (
      <Message key={message.id} post={message} />
    ))}
      </div>
    );
  },
})

How can I use this pattern with a paginated query?

Below is the paginated query I want to put into the loader

const {
    results: urls,
    status,
    loadMore,
    isLoading,
  } = usePaginatedQuery(
    api.chromeExtension.queries.getUrlsPaginated.getUrlsPaginatedQuery,
    {},
    { initialNumItems: 75 },
  )

[hearty current]

Hi @uneven charm. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

Currently, there is no direct equivalent of useSuspenseQuery for paginated queries in Convex. The established pattern for paginated queries is to use the usePaginatedQuery hook, which provides pagination-specific state and methods (results, status, loadMore, etc.) and is designed for client-side usage within React components. There is no mention in the knowledge sources of a useSuspensePaginatedQuery or similar hook that would allow you to use paginated queries in a Suspense/loader pattern as you do with useSuspenseQuery and non-paginated queries.

The loader pattern you referenced with useSuspenseQuery works because the data returned is a single array, not a paginated result. For paginated queries, you must use usePaginatedQuery inside your component, not in a loader, and manage pagination (e.g., loading more pages) via the returned loadMore function and status field. Here’s the canonical usage:

const {
  results: urls,
  status,
  loadMore,
  isLoading,
} = usePaginatedQuery(
  api.chromeExtension.queries.getUrlsPaginated.getUrlsPaginatedQuery,
  {},
  { initialNumItems: 75 },
);

This must be called inside your React component, not in a loader, and you cannot prefetch paginated data in the same way as with useSuspenseQuery and ensureQueryData in a loader. The paginated query state (including cursors and loaded pages) is managed reactively by the hook itself and is not compatible with the Suspense/loader prefetching pattern described for non-paginated queries Paginating within React Components.

Summary:

• Use usePaginatedQuery inside your component for paginated queries.
• There is no useSuspensePaginatedQuery or loader-compatible pattern for paginated queries in Convex at this time.
• Prefetching paginated data in a loader as with useSuspenseQuery is not supported.

If you need to prefetch or SSR paginated data, you would need to implement a custom solution, but this is not documented or officially supported in the current Convex API Paginated Queries.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: