Optimistic UI Updates for near instant feedback

Quick recap

Timekeeper is a weekend side project: a weekly grid for time tracking with task CRUD plus quick-add workflows like activity batches and calendar suggestions. It syncs with Firebase, but the goal is instant feedback, so the UI updates before the server confirms anything. ¹

In the last post, I shared the motivations, performance design goals, and architecture of Timekeeper. You can read the previous post here. This post dives into the optimistic UI patterns I used to make the app feel fast and responsive.

The optimistic update pattern I use

Most data writes flow through TanStack Query mutation lifecycles. The pattern looks like this:

1. Cancel refetches so stale server data cannot overwrite the optimistic UI. ²
2. Snapshot the cache for rollback.
3. Write optimistic data into the cache (often with a temporary id).
4. Rollback on error using the snapshot and show a toast.
5. Replace with server data on success (no duplicate rows). ³

A trimmed example from task creation shows the core mechanics:

onMutate: async (newTask) => {
  await queryClient.cancelQueries({ queryKey: ['tasks'] })
  const previousQueries = queryClient.getQueriesData({ queryKey: ['tasks'] })
 
  const optimisticTask: Task = {
    id: `temp-${Date.now()}`,
    ...newTask,
    createdAt: Timestamp.now(),
    updatedAt: Timestamp.now(),
  }
 
  previousQueries.forEach(([queryKey, oldData]) => {
    if (!oldData) return
    queryClient.setQueryData(queryKey, [...(oldData as Task[]), optimisticTask])
  })
 
  return { previousQueries }
},

Then I reconcile in onSuccess by swapping out the temp task and invalidating only the dependent counters (like pending task count), rather than refetching everything.

Calendar suggestions and event mappings

Calendar suggestions are more nuanced because they blend Firestore state and derived UI state. Two pieces make this feel instantaneous:

• useCalendarEventMappings mutations update the cache directly in onMutate and replace with server data in onSuccess . This avoids the race condition where a quick refetch could wipe optimistic mappings.
• useSuggestionStore optimisticAcceptedIds acts as a short-lived local filter. When a user accepts a suggestion, I hide it immediately even before the server writes a task. Once tasks arrive, the store self-cleans based on the task list . ⁴

Dismissals and batch actions

Suggestion dismissals also use optimistic entries in the query cache. Batch task creation follows the same pattern as single creation but adds multiple optimistic tasks at once and replaces them in a single pass.

Guardrails I rely on

• Avoid invalidateQueries in onSettled for optimistic flows. I already have the right state in cache and a refetch can clobber it. ⁵
• Keep optimistic IDs scoped (temp-*) so it is easy to replace them later.
• Only invalidate what you must (e.g., pending task count), not the primary list.

The core idea: trust the local cache for the UI, then reconcile with the server once it responds.