---
title: "useConvexPaginatedQuery"
description: "Reference for the paginated query composable."
canonical_url: "https://nuxt-convex.onmax.me/api-reference/use-convex-paginated-query"
---
# useConvexPaginatedQuery

> Reference for the paginated query composable.

`useConvexPaginatedQuery` subscribes to a paginated Convex query and accumulates its pages. It follows `usePaginatedQuery` from `convex/react`: each instance gets its own pagination id, and pages the server asks to split are split.

## Import

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

```ts [Vue]
import { useConvexPaginatedQuery } from 'vue-convex'
```

## Signature

```ts
function useConvexPaginatedQuery<Query extends PaginatedQueryReference>(
  query: MaybeRefOrGetter<Query>,
  args: MaybeRefOrGetter<Omit<FunctionArgs<Query>, 'paginationOpts'> | 'skip'>,
  options: {
    numItems: number
    server?: boolean
    auth?: 'required' | 'optional' | 'none'
  },
): UseConvexPaginatedQueryReturn<Item> & PromiseLike<UseConvexPaginatedQueryReturn<Item>>

interface UseConvexPaginatedQueryReturn<Item> {
  data: Readonly<Ref<Item[]>>
  error: Readonly<Ref<Error | ConvexError<Value> | null>>
  status: Readonly<Ref<'idle' | 'pending' | 'success' | 'error'>>
  isPending: ComputedRef<boolean>
  isSkipped: ComputedRef<boolean>
  isDone: Readonly<Ref<boolean>>
  isLoadingMore: Readonly<Ref<boolean>>
  loadMore: (numItems?: number) => boolean
  reset: () => void
  suspense: () => Promise<Item[]>
}
```

## Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        query
      </code>
    </td>
    
    <td>
      <code>
        FunctionReference<'query'>
      </code>
    </td>
    
    <td>
      Generated paginated query reference
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        args
      </code>
    </td>
    
    <td>
      <code>
        Omit<FunctionArgs<Query>, 'paginationOpts'> | 'skip'
      </code>
    </td>
    
    <td>
      Query args without <code>
        paginationOpts
      </code>
      
      , or <code>
        "skip"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options.numItems
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      Size of the first page, and the default for <code>
        loadMore()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options.server
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Fetch the first page during SSR when awaited
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options.auth
      </code>
    </td>
    
    <td>
      <code>
        'required' | 'optional' | 'none'
      </code>
    </td>
    
    <td>
      Same as <a href="https://nuxt-convex.onmax.me/api-reference/use-convex-query">
        useConvexQuery
      </a>
    </td>
  </tr>
</tbody>
</table>

## Return value

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        data
      </code>
    </td>
    
    <td>
      Items from all loaded pages
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        success
      </code>
      
       once the first page is loaded
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isDone
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
      
       when there are no more pages
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isLoadingMore
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
      
       while a later page is loading
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        loadMore
      </code>
    </td>
    
    <td>
      Requests the next page. Returns <code>
        false
      </code>
      
       while a page is loading, when done, or when skipped
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reset
      </code>
    </td>
    
    <td>
      Drops loaded pages and restarts from the first page
    </td>
  </tr>
</tbody>
</table>

## Behavior

- Awaiting on the server fetches the first page over HTTP and hydrates it; the client then subscribes to that page over the WebSocket
- Restarts from the first page when reactive args change, or when the server reports an `InvalidCursor`
- Clears all pages when `args` becomes `"skip"`

## Related pages

- [Pagination](https://nuxt-convex.onmax.me/vue-guide/pagination)
- [ConvexPaginatedQuery](https://nuxt-convex.onmax.me/api-reference/convex-paginated-query)
- [useConvexQuery](https://nuxt-convex.onmax.me/api-reference/use-convex-query)


## Sitemap

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