Skip to main content

Reactive arguments

Re-run a Convex query when filters, route parameters, or selected records change.

Query arguments can be a plain object, a ref, a computed value, or a getter. Each argument can also be a ref. Refs inside the object are unwrapped before execution.

Use props as arguments

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

const { data: project } = useConvexQuery(api.projects.get, { projectId })

When props.projectId changes, the composable requests the new project. Do not pass props.projectId directly: it is read once, and the query does not follow later changes.

Filter a list

ts
const search = ref('')
const includeArchived = ref(false)

const args = computed(() => ({
  search: search.value.trim(),
  includeArchived: includeArchived.value,
}))

const projects = useConvexQuery(api.projects.search, args, {
  keepPreviousData: true,
})

When either input changes, the composable requests the new argument set.

To send the same arguments to queries and mutations, see Share arguments between calls.

Add a shared argument to every query

Some values go to many queries on many pages, for example the workspace that the person selected. Pass the ref as a top-level field in each call. You do not need a wrapper composable:

app/composables/useWorkspaceId.ts
import type { Id } from '#convex/dataModel'

export const useWorkspaceId = () => useState<Id<'workspaces'> | undefined>('workspaceId')
ts
const workspaceId = useWorkspaceId()

const projects = useConvexQuery(api.projects.list, { workspaceId })

When workspaceId changes, each query runs again with the new value. When the ref holds undefined, Convex leaves the field out of the arguments. Declare the field with v.optional(...) in the Convex function, and check in the function that the person may read that workspace.

A wrapper that passes its arguments through unchanged keeps the argument types. Type the parameters with UseConvexQueryParameters:

app/composables/useAppQuery.ts
import type {
  UseConvexQueryParameters,
  UseNuxtConvexQueryOptions,
} from '@lupinum/better-convex-nuxt'
import type { FunctionReference } from 'convex/server'

export function useAppQuery<Query extends FunctionReference<'query'>>(
  query: Query,
  ...parameters: UseConvexQueryParameters<Query, UseNuxtConvexQueryOptions>
) {
  // Your own code before the query, for example logging.
  return useConvexQuery(query, ...parameters)
}

A wrapper that adds a field to the arguments needs a type cast, because TypeScript cannot check that the new object matches every query. Use a top-level ref field instead.

Keep the previous result deliberately

With keepPreviousData: true:

  1. The previous successful data remains visible for the same identity.
  2. pending becomes true for the new arguments.
  3. isStale becomes true.
  4. The new successful result replaces the previous value.
vue
<template>
  <ProjectList :projects="projects.data.value ?? []" :dimmed="projects.isStale.value" />
</template>

The default is false, which clears the old result for an explicit loading transition. When the signed-in user changes, the old data is always cleared, whatever this option says.

Skip incomplete arguments

Do not send placeholder IDs:

ts
const args = computed(() => {
  const id = route.params.projectId
  return typeof id === 'string' ? { projectId: id as Id<'projects'> } : 'skip'
})

const project = useConvexQuery(api.projects.get, args)

A route parameter is a plain string. The cast to Id<'projects'> is safe: the Convex validator checks the ID on the server, and a wrong ID makes the query fail with an error.

Use only the literal 'skip'. null is valid Convex data, and undefined represents absent query data; neither is a public skip sentinel.

Auth-dependent execution

Prefer auth: 'required' over reading auth state only to skip a private query:

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

Use a computed 'skip' when another application condition also determines whether the query is meaningful.

Keep getters pure

Vue may evaluate a computed value more than once. Argument getters should only derive data. Do not navigate, mutate state, or perform network work inside them.