Skip to main content

Connection State

Present offline, reconnecting, and pending-operation state without confusing it with backend health.

useConvexConnectionState() observes the current primary Convex client's connection state.

ts
const {
  state,
  isConnected,
  isReconnecting,
  pendingMutations,
  pendingActions,
  shouldShowOfflineUi,
} = useConvexConnectionState()

Offline banner

vue
<template>
  <aside v-if="shouldShowOfflineUi" role="status">
    {{ isReconnecting ? 'Reconnecting to live updates…' : 'Live updates are offline.' }}
  </aside>
</template>

shouldShowOfflineUi suppresses the initial hydration window so the server's disconnected snapshot does not flash an offline banner before the browser connects.

What connection means

isConnected reports the WebSocket connection. It does not prove:

  • every backend dependency is healthy;
  • a pending mutation committed;
  • the browser has general internet access;
  • a third-party API called by an action is available.

Use operation results and product queries for those facts.

Pending operations

pendingMutations and pendingActions come from the Convex connection state. They support a general “saving” indicator, not per-form attribution.

Identity changes

When the runtime replaces the primary client, connection state resets to the disconnected snapshot and observation rebinds to the replacement. Do not preserve the old client's connected badge through the transition.

Cleanup

Mounted consumers share one underlying connection-state subscription. The runtime subscribes for the first consumer and removes it after the last scope ends.

Report an issue