---
title: "Queries"
description: "Subscribe to Convex queries with reactive arguments, status and errors, skip logic, auth modes and awaitable results."
canonical_url: "https://nuxt-convex.onmax.me/vue-guide/queries"
---
# Queries

> Subscribe to Convex queries with reactive arguments, status and errors, skip logic, auth modes and awaitable results.

Use `useConvexQuery` for one live query in a component. It returns refs that update whenever Convex pushes a new result.

## Subscribe to a query

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

// No arguments needed: `list` takes none
const { data: tasks, status, error } = useConvexQuery(api.tasks.list)
</script>

<template>
  <p v-if="status === 'pending'">
    Loading…
  </p>
  <p v-else-if="status === 'error'">
    {{ error?.message }}
  </p>
  <ul v-else>
    <li v-for="task in tasks" :key="task._id">
      {{ task.title }}
    </li>
  </ul>
</template>
```

`status` is `'pending'` until the first result arrives, then `'success'` or `'error'`, and `'idle'` while the query is skipped. `isPending` and `isSkipped` are shortcuts for the first and last.

Args are optional when the query takes none. Pass them as the second argument otherwise.

## Use reactive arguments

Pass a getter, `ref` or `computed` when the arguments change over time:

```vue [src/components/ProjectTasks.vue]
<script setup lang="ts">
import type { Id } from '../../convex/_generated/dataModel'
import { useConvexQuery } from 'vue-convex'
import { api } from '../../convex/_generated/api'

const props = defineProps<{ projectId: Id<'projects'> }>()

const { data } = useConvexQuery(api.tasks.byProject, () => ({ projectId: props.projectId }))
</script>
```

When the arguments change, the new subscription starts before the old one is dropped. `data` resets to `undefined` until the new result arrives; pass `{ keepPreviousData: true }` to keep showing the old result instead. Arguments that are deep-equal don't resubscribe.

## Skip a query until you have the inputs

Return `'skip'` while the query can't run yet:

```ts
const { data, isSkipped } = useConvexQuery(
  api.users.get,
  () => props.userId ? { userId: props.userId } : 'skip',
)
```

## Wait for authentication

Use `auth: 'required'` for queries that only make sense for a signed-in user. The query stays `idle` until the user is authenticated, so it never runs anonymously first:

```ts
const { data } = useConvexQuery(api.tasks.mine, {}, { auth: 'required' })
```

`auth: 'none'` marks a query whose result is the same for everyone, which lets SSR skip resolving a token for it.

## Handle errors

`error` holds the error your function threw. `isConvexError(error, code?)` recognizes a `ConvexError` and matches its `data` or `data.code`:

```ts
import { isConvexError } from 'vue-convex'
import { computed } from 'vue'

const notFound = computed(() => isConvexError(error.value, 'NOT_FOUND'))
```

Queries never throw into your component. See [`isConvexError`](https://nuxt-convex.onmax.me/api-reference/is-convex-error) for reading `ConvexError` data.

## Wait for the first result

The return value is awaitable. Inside an async `setup()` under `<Suspense>` (which Nuxt provides), `await` waits for the first result or error, and never rejects:

```ts
const { data, error } = await useConvexQuery(api.tasks.list)
```

In a client-rendered Vue app this waits for the first WebSocket result. With server rendering, awaiting is what makes the query run on the server; see [Server Rendering](https://nuxt-convex.onmax.me/vue-guide/server-rendering), or [SSR & Hydration](https://nuxt-convex.onmax.me/nuxt-module/ssr-and-hydration) in Nuxt. `suspense()` returns a promise that rejects on error instead.

## Opt a query out of SSR

`{ server: false }` keeps a query out of the server render, even when it's awaited. It loads in the browser instead:

```ts
const { data } = await useConvexQuery(api.tasks.recent, {}, { server: false })
```

It has no effect in a client-rendered app.

## Verify the result

The query setup is working when:

- `status` goes from `pending` to `success`
- editing a document in the Convex dashboard updates `data` without a reload
- changing the reactive arguments updates the result

## Next steps

- Read [Mutations & Actions](https://nuxt-convex.onmax.me/vue-guide/mutations-and-actions) to write data back to Convex
- Read [`useConvexQuery`](https://nuxt-convex.onmax.me/api-reference/use-convex-query) for the exact signature


## Sitemap

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