---
title: "useConvexQuery"
description: "Reference for the primary read composable shared by nuxt-convex and vue-convex."
canonical_url: "https://nuxt-convex.onmax.me/api-reference/use-convex-query"
---
# useConvexQuery

> Reference for the primary read composable shared by nuxt-convex and vue-convex.

`useConvexQuery` subscribes to one Convex query and keeps the result up to date. Await it to wait for the first result, which is also what makes it run during SSR.

## Import

```ts [Nuxt]
// Auto-imported. Also exported from '#convex'.
const { data } = await useConvexQuery(api.tasks.list)
```

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

## Signature

```ts
function useConvexQuery<Query extends FunctionReference<'query'>>(
  query: MaybeRefOrGetter<Query>,
  // Optional when the query takes no arguments
  args?: MaybeRefOrGetter<FunctionArgs<Query> | 'skip'>,
  options?: UseConvexQueryOptions,
): UseConvexQueryReturn<Query> & PromiseLike<UseConvexQueryReturn<Query>>

interface UseConvexQueryOptions {
  server?: boolean
  keepPreviousData?: boolean
  auth?: 'required' | 'optional' | 'none'
}

interface UseConvexQueryReturn<Query> {
  data: Readonly<Ref<FunctionReturnType<Query> | undefined>>
  error: Readonly<Ref<Error | ConvexError<Value> | null>>
  status: Readonly<Ref<'idle' | 'pending' | 'success' | 'error'>>
  isPending: ComputedRef<boolean>
  isSkipped: ComputedRef<boolean>
  suspense: () => Promise<FunctionReturnType<Query> | undefined>
}
```

## 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 Convex query reference, or a getter returning one
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        args
      </code>
    </td>
    
    <td>
      <code>
        FunctionArgs<Query> | 'skip'
      </code>
    </td>
    
    <td>
      Query arguments, a ref or getter of them, or <code>
        'skip'
      </code>
      
       to pause the query. Optional when the query takes none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options.server
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Fetch during SSR when awaited. Defaults to the module's <code>
        ssr
      </code>
      
       option (the plugin's <code>
        server
      </code>
      
       option in Vue)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options.keepPreviousData
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Keep the previous result while the query for new args loads
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options.auth
      </code>
    </td>
    
    <td>
      <code>
        'required' | 'optional' | 'none'
      </code>
    </td>
    
    <td>
      How the query depends on the user. Defaults to <code>
        'optional'
      </code>
    </td>
  </tr>
</tbody>
</table>

### `auth`

- `'optional'`: runs with whatever auth the client has, signed in or not.
- `'required'`: stays `idle` until the user is authenticated, then runs. It replaces `computed(() => isAuthenticated.value ? args : 'skip')`.
- `'none'`: the result doesn't depend on the user. During SSR it runs without resolving the request's token.

## Return value

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

<tbody>
  <tr>
    <td>
      <code>
        data
      </code>
    </td>
    
    <td>
      <code>
        Ref<T | undefined>
      </code>
    </td>
    
    <td>
      Latest result. <code>
        undefined
      </code>
      
       while pending, skipped, or after an error
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        Ref<Error | ConvexError | null>
      </code>
    </td>
    
    <td>
      Latest error. Use <a href="https://nuxt-convex.onmax.me/api-reference/is-convex-error">
        <code>
          isConvexError
        </code>
      </a>
      
       to read <code>
        ConvexError
      </code>
      
       data
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        Ref<'idle' | 'pending' | 'success' | 'error'>
      </code>
    </td>
    
    <td>
      <code>
        idle
      </code>
      
       while skipped
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isPending
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef<boolean>
      </code>
    </td>
    
    <td>
      <code>
        status === 'pending'
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isSkipped
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef<boolean>
      </code>
    </td>
    
    <td>
      <code>
        status === 'idle'
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        suspense
      </code>
    </td>
    
    <td>
      <code>
        () => Promise<T | undefined>
      </code>
    </td>
    
    <td>
      Resolves with the first result and rejects on error
    </td>
  </tr>
</tbody>
</table>

## Behavior

- The return value is awaitable. `await useConvexQuery(...)` resolves with the same refs once the first result or error is in, and never rejects. Use `suspense()` when you want a rejection instead.
- On the server, awaiting fetches the query once over HTTP and records the result for hydration. Identical queries in one request share the fetch. Without `await`, nothing is fetched and the query renders as `pending`.
- On the client, a hydrated result is used for the first render, then the WebSocket subscription takes over. The client never fetches queries over HTTP.
- With a value already in the client's cache (another component subscribes to the same query and args), the query starts with it instead of `pending`.
- Changing args resets `data` to `undefined` unless `keepPreviousData` is set. Deep-equal args don't resubscribe.
- Args that Convex can't serialize, such as a `Date`, put the query in the `error` state instead of throwing.
- Before the runtime has a URL, the query stays `pending` and subscribes once a client connects.

## Related pages

- [Queries](https://nuxt-convex.onmax.me/vue-guide/queries)
- [SSR & Hydration](https://nuxt-convex.onmax.me/nuxt-module/ssr-and-hydration)
- [Error Handling](https://nuxt-convex.onmax.me/nuxt-module/error-handling)
- [useConvexPaginatedQuery](https://nuxt-convex.onmax.me/api-reference/use-convex-paginated-query)
- [ConvexQuery](https://nuxt-convex.onmax.me/api-reference/convex-query)


## Sitemap

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