Skip to main content

Loading and stale data

Render every query state the same way during SSR, argument changes, skips, and errors.

Use status for the main lifecycle and isStale when deliberately keeping an older same-identity result.

State meanings

StatusDataMeaning
idleundefinedSkipped, manual, anonymous required query, or not loaded yet
pendingundefined or retained valueCurrent result is loading
successQuery result, including nullThe query finished loading successfully
errorundefined or the last valueCurrent execution failed

pending is exactly equivalent to status === 'pending'.

An idle query is not running. blockedBy tells why: 'skip', 'manual' for an immediate: false query, 'auth' for an anonymous auth: 'required' query, or 'server' when the server render did not load the query and it starts in the browser. See why a query is not running.

A query that waits for the first auth state is pending with blockedBy === 'auth'. Show your skeleton then, not a sign-in hint. Show the sign-in hint only for status === 'idle' with blockedBy === 'auth'.

A query with server: false is idle with blockedBy === 'server' during the server render and hydration. Show your skeleton then too.

Render all states

vue
<script setup lang="ts">
import { api } from '#convex/api'
import type { Id } from '#convex/dataModel'

const props = defineProps<{
  organizationId: Id<'organizations'> | undefined
}>()

const { data, status, isStale, blockedBy } = useConvexQuery(
  api.projects.list,
  () => (props.organizationId ? { organizationId: props.organizationId } : 'skip'),
  { keepPreviousData: true },
)
</script>

<template>
  <ProjectSkeleton v-if="data === undefined && (status === 'pending' || blockedBy === 'server')" />

  <p v-else-if="status === 'error' && data === undefined" role="alert">
    Projects could not be loaded.
  </p>

  <p v-else-if="blockedBy === 'skip'">Select an organization.</p>

  <section v-else :aria-busy="status === 'pending'">
    <p v-if="status === 'error'" role="status">
      Projects could not be updated. The list shows the last loaded projects.
    </p>
    <p v-else-if="isStale">Updating results…</p>
    <ProjectList :projects="data ?? []" />
  </section>
</template>

Do not use a truthiness check as the loading contract. A successful query can return null, while a stale query can be pending with data still visible.

Show the full error view only when status === 'error' and data is undefined. A query that fails after it loaded keeps its last value, so show that value with a short notice.

Presentation fallbacks

Keep placeholders in presentation code so query state continues to describe only real query results:

ts
const projects = useConvexQuery(api.projects.list, {})
const visibleProjects = computed(() => projects.data.value ?? [])

Errors after previous data

When a query that already has data fails, data keeps the last value, status is 'error', and isStale is true. Label the value as out of date, as in the template above. Do not hide it behind the error view. When the signed-in user changes, the composable clears the previous user's data automatically.

Why there is no refresh

Convex keeps every subscribed query current. When the data that a query read changes, Convex runs the query again and sends the new result. A manual refresh cannot return newer data, so the query composables have no refresh(). If a result depends on time, pass the time as an argument; see Time-based data. For user-facing error text, see Error messages.