#how to pass arguments into usePaginatedQuery

12 messages · Page 1 of 1 (latest)

silver cape
#

my code below is getting lint errors.

const {
  results,
  status,
  loadMore,
  isLoading
} = usePaginatedQuery(
  api.content.doQuery,
  {
    paginationOpts: { numItems: 1 },
    user: "user"
  },
  { initialNumItems: 1 }
)
clever heraldBOT
#

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

#

To pass arguments into usePaginatedQuery, you should not include the paginationOpts property in your arguments object. The usePaginatedQuery hook automatically injects paginationOpts for you. You only need to provide the other arguments your query expects (excluding paginationOpts), and specify the initialNumItems in the options object.

Here's how you should structure your code:

const {
  results,
  status,
  loadMore,
  isLoading
} = usePaginatedQuery(
  api.content.doQuery,
  { user: "user" }, // Do NOT include paginationOpts here
  { initialNumItems: 1 }
);

Explanation:

  • The second argument to usePaginatedQuery should be an object with all arguments your query expects, except for paginationOpts.
  • The third argument is an options object where you specify initialNumItems.

This is confirmed in the Convex documentation:

The arguments to this hook are:

  • The name of the paginated query function.
  • The arguments object to pass to the query function, excluding the paginationOpts (that's injected by the hook).
  • An options object with the initialNumItems to load on the first page.

See example in the docs

So, just remove paginationOpts from your arguments object and your lint errors should be resolved.

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

#

@silver cape Kapa.ai is still learning and improving, please let me know how I did by reacting below.

silver cape
#

@clever herald now change the implementation. i want to also implement pagination on the ui level. imagine i have 36 items in the table and show 6 item per page. when i click on page 2, it should fetch the 7th to 12th item. can u fix the query?

clever heraldBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

Convex’s built-in usePaginatedQuery and .paginate() are designed for cursor-based (not offset-based) pagination, which is ideal for infinite scroll or "load more" UIs. However, if you want classic page-based navigation (e.g., page 2 shows items 7–12), you need to implement offset-based pagination yourself. The knowledge sources confirm that usePaginatedQuery does not support offset-based pagination out of the box, and you cannot simply pass an offset to .paginate() or usePaginatedQuery see discussion.

Recommended approach:

  • Write a custom query that takes a page argument and uses .take() and .skip() (or equivalent logic) to fetch the correct slice of data.
  • Use useQuery (not usePaginatedQuery) in your React component.

Example implementation:

Convex query:

const PAGE_SIZE = 6;

export const getPage = query({
  args: {
    page: v.number(),
  },
  handler: async (ctx, args) => {
    const start = (args.page - 1) * PAGE_SIZE;
    return await ctx.db
      .query("content")
      .order("desc") // or your preferred order
      .skip(start)
      .take(PAGE_SIZE);
  },
});

(Note: .skip() is not a Convex API method, but the pattern is described in the Discord thread. If you need true offset, you may need to use an auto-incrementing field or a workaround as described below.)

If you need to use an auto-incrementing field:

  • Add an incrementingId to your documents.
  • Query using .withIndex("incrementingId_index", ...) and .gte() as shown in the Discord thread:
const PAGE_SIZE = 6;
#

export const getPage = query({
args: {
page: v.number(),
},
handler: async (ctx, args) => {
const startId = (args.page - 1) * PAGE_SIZE + 1;
return await ctx.db
.query("content")
.withIndex("incrementingId_index", (q) => q.gte("incrementingId", startId))
.take(PAGE_SIZE);
},
});

[See the full discussion and example in the Discord thread](<https://discord.com/channels/1019350475847499849/1291118936594579637>).

**React usage:**
```ts
const page = 2; // for example
const results = useQuery(api.content.getPage, { page });

Summary:

  • For classic page-based navigation, use a custom query with a page argument and useQuery.
  • usePaginatedQuery is not suitable for offset-based pagination or "jump to page N" UIs see Discord discussion.

If you need more details on how to set up the auto-incrementing field, let me know!

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

#

@silver cape Kapa.ai is still learning and improving, please let me know how I did by reacting below.

silver cape
#

@clever herald im running into "Property 'skip' does not exist on type 'OrderedQuery"

clever heraldBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

You're correct—Convex's OrderedQuery does not have a .skip() method. This is a common point of confusion, and the knowledge sources confirm that offset-based pagination (i.e., skipping N items) is not natively supported in Convex's query API. Instead, Convex encourages cursor-based pagination using .paginate() or, for true offset-based pagination, the use of the Aggregate component to efficiently jump to a specific offset in large datasets.

From the Discord support threads:

"we can’t just tell the database 'skip over 500 documents, then give a page of size 50'... if you actually want offset-based pagination, you can use the Aggregate component, because once you have aggregates, it’s feasible to say 'skip over 500 documents'"
Discord: Understanding usePaginatedQuery

What to do instead:

  • For classic "jump to page N" pagination, you need to use the Aggregate component to get the key at a given offset, then query from that key using an index. This is more complex than using .skip(), but it's the recommended approach for offset-based pagination in Convex.
  • If you only need cursor-based/infinite scroll pagination, use .paginate() and usePaginatedQuery.

Summary:
There is no .skip() method in Convex's query API. For offset-based pagination, use the Aggregate component as described in the Convex Aggregate docs and in the Discord threads above. If you need help with an example using Aggregate, let me know!

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