UX Patterns Guide
UI + UX Feedback, Status, And System State standard

Sync state

Expose sync state as a scoped reconciliation surface that names the local and remote copy status, keeps per-item progress and failures visible, preserves local data, and provides retry, cancel, export, resume, or review actions.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • Local changes, files, messages, uploads, or records need to reconcile with a remote service or another device.
  • Users can continue work while sync happens asynchronously or after reconnect.
  • Partial success, retry, pause, conflict, or last-synced freshness affects user trust or next action.
  • The product needs to distinguish local durability from cloud or server confirmation.

Avoid when

  • The product has no local copy or queued work and a simple loading, success, or error state is enough.
  • The user only needs to know the device is offline and no reconciliation is happening yet.
  • The operation is a single short request with no recoverable local state.
  • A confirmed failure blocks the whole view and needs a full error recovery surface.
  • A numeric progress bar alone communicates the useful state and remote acceptance is not in question.

Problem it prevents

Users have local changes, downloaded files, queued uploads, or background requests whose server or peer copy may be pending, in progress, accepted, partially accepted, failed, paused, or conflicting.

Pattern anatomy

What a strong implementation has to make clear

User need

The product stores or edits data locally before remote acceptance, or it downloads remote content for local use.

Pattern promise

Expose sync state as a scoped reconciliation surface that names the local and remote copy status, keeps per-item progress and failures visible, preserves local data, and provides retry, cancel, export, resume, or review actions.

Required state

Local saved state for data persisted on the device but not yet sent.

Recovery path

Users close the app after a green status even though work was only saved locally.

Access contract

Use visible text and accessible names for statuses; do not rely on spinning arrows, checkmarks, color, or icon overlays alone.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A field report queue shows 5 local changes: notes synced, two photos uploading, meter reading queued, signature failed with Retry, and supervisor comment needs review.
  • A file list uses separate badges for Available offline, Syncing, Sync error, and Online-only, with details available from the affected row.
  • A user reconnects after editing offline and sees the queue move from local saved to syncing, then to one failed photo with retry while the accepted notes remain synced.
  • A user opens the same record on another device and sees that the server copy is current as of 11:08 while one local edit still needs review.
Weak implementation

Vague, hidden, hard to recover from

  • A single green Saved badge appears while several attachments are still queued.
  • An endless spinner says Syncing with no item count, failure details, last sync time, or retry action.
  • The offline banner disappears after reconnect, but hidden queued changes keep failing in the background.
  • A sync error toast disappears before the user can identify which file failed.
UI guidance
  • Show sync state close to the object or queue it describes, using labels such as Local saved, Queued, Syncing, Synced, Partially synced, Failed, Paused, and Conflict needs review.
  • Separate device-local persistence from remote acceptance; a green synced status is only appropriate after the server or target peer has accepted the change.
UX guidance
  • Use sync state to keep users confident while local changes, remote copies, attachments, messages, or records reconcile across devices, services, or background workers.
  • Make partial progress actionable by exposing per-item status, last successful sync time, retry/cancel/export choices, and a clear handoff when a conflict or validation issue needs review.
Implementation contract

What the implementation must handle

States

  • Local saved state for data persisted on the device but not yet sent.
  • Queued state for work waiting for a sync attempt.
  • Syncing state with scope, item count, or operation label.
  • Synced state after remote acceptance.

Interaction

  • The sync surface never upgrades local saved or queued work to synced until the remote system confirms acceptance.
  • Queue-level status summarizes counts while item-level rows show which object owns each status.
  • Retry acts on failed items or a clearly named queue; it does not duplicate already accepted changes.
  • Cancel or remove actions explain whether they discard only queued local work or also affect the remote copy.

Accessibility

  • Use visible text and accessible names for statuses; do not rely on spinning arrows, checkmarks, color, or icon overlays alone.
  • Expose sync summaries through polite status updates when state changes matter to the current task.
  • Keep retry, cancel, export, pause, resume, and review actions keyboard reachable in the affected item row or queue panel.
  • Associate failed item messages with their owning object and action.

Review

  • What exactly is local, what exactly is remote, and which copy is current?
  • What event proves that this item is synced: transfer complete, server accepted, peer acknowledged, or later validation passed?
  • Can users identify which queue item failed and what action fixes it?
  • How does the UI represent partial success without implying the whole task is done?
Interactive lab

Inspect the states before you copy the pattern

Reconcile local and server changes

Move a field report sync queue through local saved, queued, syncing, synced, partial, failed, retrying, and conflict-needs-review states; compare with hidden queue, endless spinner, false synced, and cleared-failure misuse.

Sync state
Interactive demo is ready

Launch the live UI/UX lab when you want to inspect states, keyboard behavior, and common failure modes.

State To Inspect

Local saved state for data persisted on the device but not yet sent.

Keyboard / Access

Focus remains stable when background sync updates status.

Avoid Generating

Calling local persistence Synced before remote acceptance.
Evidence trail

Source-backed claims behind this guidance

Workbox Background Sync

Chrome for Developers - checked

Workbox supports queued failed requests, sync-event replay, browser-managed retry timing, and retention limits.

Microsoft OneDrive sync icons

Microsoft Support - checked

OneDrive supports visible sync states for in-progress, error, paused, online-only, locally available, and offline-available files.

Full agent/debug reference

Problem Context

  • The product stores or edits data locally before remote acceptance, or it downloads remote content for local use.
  • Sync can happen after reconnect, in the background, across devices, or after a service worker, native client, or cloud service retries queued work.
  • Users need to know whether work is merely local, queued, actively transferring, accepted remotely, stuck, paused, partially synced, or blocked by conflict or validation.

Selection Rules

  • Choose sync state when local and remote copies both matter and their reconciliation status affects trust, next action, or data integrity.
  • Label local saved separately from remote synced until the server, service, or peer confirms acceptance.
  • Show per-item status when different queue items can be queued, in progress, accepted, failed, paused, or conflicting at the same time.
  • Show last successful sync time or server version when freshness or cross-device confidence matters.
  • Keep failed or conflicting local work visible with retry, edit, cancel, export, or review actions.
  • Use offline state when the primary condition is no connection and the question is what still works locally.
  • Use progress bar when the measurable percentage is the primary useful signal, not when users need acceptance, queue, or conflict status.
  • Use error state when a failed sync item has become a blocking recovery surface rather than one state in an active queue.
  • Use draft state when the main concern is unpublished authoring state, even if that draft may later sync.
  • Escalate from passive status to persistent recovery when sync failure affects submission, payment, legal records, medical records, file integrity, or collaboration.

Required States

  • Local saved state for data persisted on the device but not yet sent.
  • Queued state for work waiting for a sync attempt.
  • Syncing state with scope, item count, or operation label.
  • Synced state after remote acceptance.
  • Partially synced state when some queue items succeeded and others did not.
  • Failed sync state that preserves local work and exposes recovery.
  • Retrying state that differs from idle failure.
  • Paused state for user, metered-network, account, battery, or policy pause.
  • Conflict-needs-review state that preserves both local and server information.
  • Last successful sync timestamp or version state.

Interaction Contract

  • The sync surface never upgrades local saved or queued work to synced until the remote system confirms acceptance.
  • Queue-level status summarizes counts while item-level rows show which object owns each status.
  • Retry acts on failed items or a clearly named queue; it does not duplicate already accepted changes.
  • Cancel or remove actions explain whether they discard only queued local work or also affect the remote copy.
  • Partial success remains visible until every failed, paused, or conflict item is resolved.
  • Background sync updates are announced at meaningful boundaries such as queued, syncing, synced, failed, or review needed.
  • The user can identify whether a problem is network retry, account sign-in, server validation, unsupported file type, policy block, or conflict.

Implementation Checklist

  • Define canonical sync statuses in the data model, not just in display text.
  • Store local queue entries with stable IDs, object names, timestamps, retry counts, server request identifiers, and recoverable local payloads.
  • Record remote acceptance separately from local persistence and transfer completion.
  • Render a compact summary plus expandable item-level rows when queues contain more than one object.
  • Expose retry, cancel, export local copy, view details, and review conflict actions according to the item status.
  • Use background sync, native sync queues, upload managers, or job workers only when the UI can surface their states honestly.
  • Test reconnect, duplicate retry, partial server success, app restart, account sign-out, policy-blocked files, quota failure, server validation failure, and multi-device conflict.

Common Generated-UI Mistakes

  • Calling local persistence Synced before remote acceptance.
  • Showing only one spinner for a mixed queue of succeeded, failed, and pending items.
  • Hiding failed sync work in a transient toast.
  • Clearing local data after a failed retry.
  • Treating server validation failure, offline mode, account pause, and conflict as the same sync message.
  • Using a percentage as proof of save when server acceptance still has not happened.
  • Removing the sync indicator immediately after reconnect even though queued work remains.

Critique Questions

  • What exactly is local, what exactly is remote, and which copy is current?
  • What event proves that this item is synced: transfer complete, server accepted, peer acknowledged, or later validation passed?
  • Can users identify which queue item failed and what action fixes it?
  • How does the UI represent partial success without implying the whole task is done?
  • What happens to local work after app restart, account switch, retry exhaustion, or conflict?
  • Does the status explain whether sync is paused, blocked, retrying, failed, or waiting for review?
Accessibility
  • Use visible text and accessible names for statuses; do not rely on spinning arrows, checkmarks, color, or icon overlays alone.
  • Expose sync summaries through polite status updates when state changes matter to the current task.
  • Keep retry, cancel, export, pause, resume, and review actions keyboard reachable in the affected item row or queue panel.
  • Associate failed item messages with their owning object and action.
  • Avoid announcing every byte-level change; announce meaningful transitions such as queued, syncing, synced, failed, paused, and review needed.
  • Make last-synced timestamps and local-vs-remote copy labels available to assistive technology near the affected content.
Keyboard Behavior
  • Focus remains stable when background sync updates status.
  • Queue rows, retry buttons, cancel buttons, export actions, and review-conflict controls follow a predictable tab order.
  • If the user activates Retry, focus remains on the item or moves to the updated status message when retry begins.
  • When a modal or separate review flow opens for a conflict, focus moves into that flow and returns to the originating queue item on close.
  • Paused, failed, and review-needed statuses do not hide actions behind hover-only affordances.
Variants
  • Inline row sync badge
  • Global sync summary
  • Outbox queue
  • File sync overlay
  • Background upload queue
  • Partial sync report
  • Paused sync notice
  • Sync error recovery
  • Conflict review handoff
  • Last synced timestamp

Verification

Last verified: