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
| Status | Data | Meaning |
|---|---|---|
idle | undefined | Skipped, manual, anonymous required query, or not loaded yet |
pending | undefined or retained value | Current result is loading |
success | Query result, including null | The query finished loading successfully |
error | undefined or the last value | Current 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
<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:
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.