UsePaginatedQueryReturn

Defined in: packages/react/src/hooks/usePaginatedQuery.ts:61

Return type of usePaginatedCollection hook.

Mimics Convex’s usePaginatedQuery API for consistency.

Type Parameters

TDocument

TDocument extends VexDocument = VexDocument

Properties

error?

optional error?: unknown

Defined in: packages/react/src/hooks/usePaginatedQuery.ts:149

The query’s error, when the underlying fetch rejected — undefined while loading or once it has succeeded. Surfaces a VexError thrown server-side (e.g. UNINDEXED_SORT) so a caller like ListViewQueryError (Step 10) can render a specific message instead of the empty-results state a rejected query would otherwise look like.

---

isDone

isDone: boolean

Defined in: packages/react/src/hooks/usePaginatedQuery.ts:90

Whether all documents have been loaded. When true, Load More button should be hidden.

---

isFetching

isFetching: boolean

Defined in: packages/react/src/hooks/usePaginatedQuery.ts:114

TanStack’s own “a fetch is in flight for the CURRENT query identity” flag. Reliable against the fake test backend’s genuinely-awaited t.run() (hooksSuite.tsx asserts against it directly), but NOT against the real Convex client: live updates arrive via a direct queryClient.setQueryData write from its websocket subscription (@convex-dev/react-query), never a tracked refetch, so this can read false throughout a query-identity change that visibly swaps results (confirmed live, 2026-11-01 investigation) — use isSettling for a search/sort/filter-driven spinner instead; this is kept for Load More’s own in-flight state and existing test coverage against the fake backend.

---

isPending

isPending: boolean

Defined in: packages/react/src/hooks/usePaginatedQuery.ts:101

Whether a query is currently in flight. Use for loading states on Load More button.

---

isPlaceholderData

isPlaceholderData: boolean

Defined in: packages/react/src/hooks/usePaginatedQuery.ts:140

TanStack’s own flag (Decision 46): true while results is showing the PREVIOUS query’s rows because placeholderData: keepPreviousData is keeping them on screen during a query-identity change (e.g. a view switch), not the CURRENT query’s own data yet. Distinct from isFetching — that’s true for ANY in-flight fetch under the SAME query identity too (a Load More page, a background refetch); this is specifically “what you’re looking at right now is stale.” A caller (DataTable’s isRefetching prop) uses this to dim the table body and mark it aria-busy without ever rendering a blank/loading frame.

---

isSettling

isSettling: boolean

Defined in: packages/react/src/hooks/usePaginatedQuery.ts:127

true from the render where the query’s identity (where/sort/drafts/numItems) changes until results has been synced with the REAL answer for that new identity — unlike isFetching/isPlaceholderData, this is derived from results actually having been written, not from React Query’s own fetch-lifecycle bookkeeping, so it works identically whether the new answer arrives via a tracked refetch or a live websocket push straight into the cache. A search field reads this (not isFetching) to show its own in-input spinner while the previous page’s rows stay on screen. false during a Load More (a cursor change under the SAME identity) — that has its own loading state (isPending), not a “the page you’re looking at is stale” one.

---

loadMore

loadMore: () => void

Defined in: packages/react/src/hooks/usePaginatedQuery.ts:95

Load more documents. Fetches the next page using initialNumItems.

Returns

void

---

results

results: TDocument[]

Defined in: packages/react/src/hooks/usePaginatedQuery.ts:66

All loaded documents (accumulated across Load More calls). Starts with first page, grows as user clicks Load More.

---

retry

retry: () => void

Defined in: packages/react/src/hooks/usePaginatedQuery.ts:152

Re-runs the failed query, without resetting any already-loaded pages.

Returns

void

---

totalDocs

totalDocs: number | null | undefined

Defined in: packages/react/src/hooks/usePaginatedQuery.ts:75

Total document count across all pages.

• number when count succeeded
• null when collection has >32k documents (Convex limit)
• undefined when count hasn’t loaded yet or includeTotalCount=false

---

totalDocsCapped

totalDocsCapped: boolean

Defined in: packages/react/src/hooks/usePaginatedQuery.ts:84

Whether totalDocs is a floor, not an exact count — find counted with take(countLimit + 1) and hit the cap (Design Decision 35). false once totalDocs is null/undefined (count not loaded, or the collection is below the old 32k scan limit this hook never hits anymore since find itself caps the scan).