Queries

Use useConvexQuery when you want one reactive query subscription in a Vue or Nuxt component.

Subscribe to a query

<script setup lang="ts">
import { useConvexQuery } from 'vue-convex'
import { api } from '../convex/_generated/api'

const { data, error, isPending, suspense } = useConvexQuery(
  api.tasks.list,
  { userId: 'user_123' },
)

await suspense()
</script>

useConvexQuery can fetch once on the server through ConvexHttpClient and then attach a realtime subscription on the client.

Use reactive arguments

Pass a ref, computed, or getter when the query arguments can change over time.

<script setup lang="ts">
import { useConvexQuery } from 'vue-convex'
import { api } from '../convex/_generated/api'

const props = defineProps<{ userId: string }>()

const { data } = useConvexQuery(
  api.tasks.list,
  computed(() => ({ userId: props.userId })),
)
</script>

When the arguments change, the old subscription is cleaned up and a new one starts automatically.

Skip a query until you have the inputs

Pass "skip" when the query should stay inactive until another piece of state is ready.

<script setup lang="ts">
import { useConvexQuery } from 'vue-convex'
import { api } from '../convex/_generated/api'

const props = defineProps<{ userId?: string }>()

const { data, isSkipped } = useConvexQuery(
  api.users.get,
  computed(() => props.userId ? { userId: props.userId } : 'skip'),
)
</script>

Disable SSR for auth-sensitive reads

Use { server: false } when the server does not have the browser auth context you need.

const { data } = useConvexQuery(api.tasks.myTasks, {}, { server: false })

This keeps the query client-only and avoids an SSR request that would run without the user session.

Verify the result

The query setup is working when:

• await suspense() resolves
• data updates after the first response
• changing the reactive arguments updates the subscription

Next steps

• Read Mutations & Actions to write data back to Convex
• Read useConvexQuery for the exact return shape