Skip to main content
useSyncStatus returns the current synchronization status between the local client session and the leader thread. The component re-renders whenever the status changes.

​
Function signature

function useSyncStatus(options: { store: Store<any> }): SyncStatus
Alternatively, call store.useSyncStatus() after getting a store from useStore — the store option is bound automatically.

​
Parameters

​
options.store
Store<any>
required
The store instance to subscribe to. Pass this explicitly when using the standalone hook from @livestore/react, or omit it when calling store.useSyncStatus() from a store returned by useStore.

​
Return value

​
status
SyncStatus
The current sync status object.

​
Usage

​
Basic sync indicator

import { useStore } from '@livestore/react'

function SyncIndicator() {
  const store = useStore(myStoreOptions)
  const status = store.useSyncStatus()

  return (
    <span>
      {status.isSynced
        ? 'Synced'
        : `Syncing (${status.pendingCount} pending)…`}
    </span>
  )
}

​
Standalone hook

import { useSyncStatus } from '@livestore/react'

function SyncIndicator({ store }) {
  const status = useSyncStatus({ store })

  return (
    <span>{status.isSynced ? '✓ Synced' : `Syncing (${status.pendingCount} pending)…`}</span>
  )
}

​
Visual connection badge

function ConnectionBadge() {
  const store = useStore(myStoreOptions)
  const status = store.useSyncStatus()

  return (
    <div className={`badge ${status.isSynced ? 'badge--synced' : 'badge--pending'}`}>
      {status.isSynced ? 'Online' : `${status.pendingCount} unsynced`}
    </div>
  )
}

​
Blocking navigation while unsynced

function SaveButton() {
  const store = useStore(myStoreOptions)
  const status = store.useSyncStatus()

  const handleSave = () => {
    store.commit(events.documentSaved({ id: docId }))
  }

  return (
    <button onClick={handleSave} disabled={!status.isSynced}>
      {status.isSynced ? 'Save' : 'Saving…'}
    </button>
  )
}

​
How it works

useSyncStatus reads the initial status synchronously from store.syncStatus(), then subscribes via store.subscribeSyncStatus(). The component re-renders whenever the status object changes. The hook exposes a debug label LiveStore:useSyncStatus:synced or LiveStore:useSyncStatus:pending in React DevTools.
isSynced reflects synchronization between the client session and the leader thread, not between the leader thread and a remote sync backend. To check remote connectivity, use a separate network status indicator.

Build docs developers (and LLMs) love

Get started for freeTalk to us