---
title: "Pagination"
description: "Build client-side paginated feeds with useConvexPaginatedQuery and Convex paginated query functions."
canonical_url: "https://nuxt-convex.onmax.me/vue-guide/pagination"
---
# Pagination

> Build client-side paginated feeds with useConvexPaginatedQuery and Convex paginated query functions.

Use `useConvexPaginatedQuery` for a feed that loads one page at a time. Every loaded page stays subscribed, so edits to any item show up live.

## Write the Convex query

Your Convex query must accept `paginationOpts` and return a `PaginationResult`.

```ts [convex/tasks.ts]
import { paginationOptsValidator } from 'convex/server'
import { v } from 'convex/values'
import { query } from './_generated/server'

export const paginated = query({
  args: {
    isCompleted: v.optional(v.boolean()),
    paginationOpts: paginationOptsValidator,
  },
  handler: async (ctx, { isCompleted, paginationOpts }) => {
    let q = ctx.db.query('tasks').order('desc')
    if (isCompleted !== undefined)
      q = q.filter(doc => doc.eq(doc.field('isCompleted'), isCompleted))
    return await q.paginate(paginationOpts)
  },
})
```

You do not pass `paginationOpts` from the component. `useConvexPaginatedQuery` injects it for you.

## Subscribe from the client

```vue [src/components/TaskFeed.vue]
<script setup lang="ts">
import { useConvexPaginatedQuery } from 'vue-convex'
import { api } from '../../convex/_generated/api'

const { data, isPending, isDone, isLoadingMore, loadMore } = useConvexPaginatedQuery(
  api.tasks.paginated,
  {},
  { numItems: 20 },
)
</script>
```

Pages stay live. The first page covers everything from the start of the list up to where it ended when it loaded, so rows inserted into that range join it and it can grow past `numItems`. If the list was empty when the first page loaded, every new row lands there and `isDone` stays `true`. This matches `convex/react`.

## Reset on filter changes

Reactive arguments automatically clear the current pages and restart from the first page.

```vue [src/components/FilteredFeed.vue]
<script setup lang="ts">
import { useConvexPaginatedQuery } from 'vue-convex'
import { computed, ref } from 'vue'
import { api } from '../../convex/_generated/api'

const showCompleted = ref(false)

const { data, loadMore, isDone } = useConvexPaginatedQuery(
  api.tasks.paginated,
  computed(() => ({ isCompleted: showCompleted.value })),
  { numItems: 20 },
)
</script>
```

## Skip pagination until the inputs exist

```ts
const { data, isSkipped } = useConvexPaginatedQuery(
  api.tasks.byProject,
  () => projectId.value ? { projectId: projectId.value } : 'skip',
  { numItems: 20 },
)
```

For queries that need a signed-in user, `{ numItems: 20, auth: 'required' }` does the same without the getter.

## Use the optimistic helpers when needed

`vue-convex` exports `insertAtTop`, `insertAtBottomIfLoaded`, `insertAtPosition` and `optimisticallyUpdateValueInPaginatedQuery`, the same helpers as `convex/react`, for optimistic updates on paginated queries:

```ts
import { insertAtTop, useConvexMutation } from 'vue-convex'

const { mutate: addTask } = useConvexMutation(api.tasks.add, {
  optimisticUpdate: (localStore, args) => insertAtTop({
    paginatedQuery: api.tasks.paginated,
    argsToMatch: {},
    localQueryStore: localStore,
    // A placeholder document; the server result replaces it when the mutation lands
    item: placeholderTask(args),
  }),
})
```

## Verify the result

The setup is working when:

- the first page loads into `data`
- `loadMore()` appends another page
- changing the arguments resets the feed

## Render the first page on the server

Like `useConvexQuery`, the composable is awaitable. With server rendering (Nuxt, or your own [SSR setup](https://nuxt-convex.onmax.me/vue-guide/server-rendering)), awaiting it fetches the first page on the server and hydrates it; `loadMore()` then continues in the browser.

```ts
const { data, loadMore } = await useConvexPaginatedQuery(api.tasks.paginated, {}, { numItems: 20 })
```

Pass `server: false` in the options to keep it client-only.

## Next steps

- Read [File Storage](https://nuxt-convex.onmax.me/vue-guide/file-storage) if each item in the feed needs uploads or file URLs
- Read [`useConvexPaginatedQuery`](https://nuxt-convex.onmax.me/api-reference/use-convex-paginated-query) for the exact return shape


## Sitemap

See the full [sitemap](https://nuxt-convex.onmax.me/sitemap.md) for all pages.
