React Optimistic Updates

Optimistic updates show changes instantly before server confirmation. Here's how to implement them.

Why Optimistic Updates?#

// Without optimistic updates - feels slow
async function addTodo(text: string) {
  setLoading(true);
  const todo = await api.createTodo(text); // Wait for server
  setTodos(prev => [...prev, todo]);
  setLoading(false);
}

// With optimistic updates - instant feedback
async function addTodoOptimistic(text: string) {
  const tempId = Date.now().toString();
  const optimisticTodo = { id: tempId, text, completed: false };

  // Update UI immediately
  setTodos(prev => [...prev, optimisticTodo]);

  try {
    // Sync with server
    const realTodo = await api.createTodo(text);
    setTodos(prev => prev.map(t =>
      t.id === tempId ? realTodo : t
    ));
  } catch (error) {
    // Rollback on failure
    setTodos(prev => prev.filter(t => t.id !== tempId));
    showError('Failed to create todo');
  }
}

Basic Implementation#

import { useState, useCallback } from 'react';

interface Todo {
  id: string;
  text: string;
  completed: boolean;
  isPending?: boolean;
}

function TodoList() {
  const [todos, setTodos] = useState<Todo[]>([]);

  const addTodo = useCallback(async (text: string) => {
    const tempId = `temp-${Date.now()}`;
    const optimisticTodo: Todo = {
      id: tempId,
      text,
      completed: false,
      isPending: true,
    };

    // Optimistic update
    setTodos(prev => [...prev, optimisticTodo]);

    try {
      const todo = await api.createTodo(text);
      setTodos(prev =>
        prev.map(t => (t.id === tempId ? { ...todo, isPending: false } : t))
      );
    } catch {
      // Rollback
      setTodos(prev => prev.filter(t => t.id !== tempId));
    }
  }, []);

  const toggleTodo = useCallback(async (id: string) => {
    const todo = todos.find(t => t.id === id);
    if (!todo) return;

    // Optimistic update
    setTodos(prev =>
      prev.map(t =>
        t.id === id ? { ...t, completed: !t.completed, isPending: true } : t
      )
    );

    try {
      await api.updateTodo(id, { completed: !todo.completed });
      setTodos(prev =>
        prev.map(t => (t.id === id ? { ...t, isPending: false } : t))
      );
    } catch {
      // Rollback
      setTodos(prev =>
        prev.map(t =>
          t.id === id ? { ...t, completed: todo.completed, isPending: false } : t
        )
      );
    }
  }, [todos]);

  const deleteTodo = useCallback(async (id: string) => {
    const todo = todos.find(t => t.id === id);
    if (!todo) return;

    // Optimistic delete
    setTodos(prev => prev.filter(t => t.id !== id));

    try {
      await api.deleteTodo(id);
    } catch {
      // Rollback
      setTodos(prev => [...prev, todo]);
    }
  }, [todos]);

  return (
    <ul>
      {todos.map(todo => (
        <li
          key={todo.id}
          style={{ opacity: todo.isPending ? 0.5 : 1 }}
        >
          <input
            type="checkbox"
            checked={todo.completed}
            onChange={() => toggleTodo(todo.id)}
            disabled={todo.isPending}
          />
          {todo.text}
          <button onClick={() => deleteTodo(todo.id)}>Delete</button>
        </li>
      ))}
    </ul>
  );
}

Custom Hook#

interface UseOptimisticOptions<T, TCreate, TUpdate> {
  fetchItems: () => Promise<T[]>;
  createItem: (data: TCreate) => Promise<T>;
  updateItem: (id: string, data: TUpdate) => Promise<T>;
  deleteItem: (id: string) => Promise<void>;
  getId: (item: T) => string;
}

function useOptimisticCRUD<T, TCreate, TUpdate>({
  fetchItems,
  createItem,
  updateItem,
  deleteItem,
  getId,
}: UseOptimisticOptions<T, TCreate, TUpdate>) {
  const [items, setItems] = useState<(T & { _pending?: boolean })[]>([]);
  const [error, setError] = useState<Error | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchItems()
      .then(setItems)
      .catch(setError)
      .finally(() => setLoading(false));
  }, [fetchItems]);

  const create = useCallback(async (
    data: TCreate,
    optimisticData: Partial<T>
  ) => {
    const tempId = `temp-${Date.now()}`;
    const optimisticItem = {
      ...optimisticData,
      _pending: true,
    } as T & { _pending: boolean };

    setItems(prev => [...prev, optimisticItem]);

    try {
      const created = await createItem(data);
      setItems(prev =>
        prev.map(item =>
          getId(item) === tempId ? { ...created, _pending: false } : item
        )
      );
      return created;
    } catch (err) {
      setItems(prev => prev.filter(item => getId(item) !== tempId));
      throw err;
    }
  }, [createItem, getId]);

  const update = useCallback(async (
    id: string,
    data: TUpdate
  ) => {
    const original = items.find(item => getId(item) === id);
    if (!original) return;

    setItems(prev =>
      prev.map(item =>
        getId(item) === id ? { ...item, ...data, _pending: true } : item
      )
    );

    try {
      const updated = await updateItem(id, data);
      setItems(prev =>
        prev.map(item =>
          getId(item) === id ? { ...updated, _pending: false } : item
        )
      );
      return updated;
    } catch (err) {
      setItems(prev =>
        prev.map(item =>
          getId(item) === id ? { ...original, _pending: false } : item
        )
      );
      throw err;
    }
  }, [items, updateItem, getId]);

  const remove = useCallback(async (id: string) => {
    const original = items.find(item => getId(item) === id);
    if (!original) return;

    setItems(prev => prev.filter(item => getId(item) !== id));

    try {
      await deleteItem(id);
    } catch (err) {
      setItems(prev => {
        const index = prev.findIndex(item => getId(item) > id);
        const newItems = [...prev];
        newItems.splice(index === -1 ? prev.length : index, 0, original);
        return newItems;
      });
      throw err;
    }
  }, [items, deleteItem, getId]);

  return {
    items,
    loading,
    error,
    create,
    update,
    remove,
  };
}

With React Query#

import { useMutation, useQueryClient } from '@tanstack/react-query';

function useTodos() {
  const queryClient = useQueryClient();

  const addMutation = useMutation({
    mutationFn: (text: string) => api.createTodo(text),
    onMutate: async (text) => {
      // Cancel outgoing refetches
      await queryClient.cancelQueries({ queryKey: ['todos'] });

      // Snapshot previous value
      const previousTodos = queryClient.getQueryData(['todos']);

      // Optimistic update
      queryClient.setQueryData(['todos'], (old: Todo[]) => [
        ...old,
        { id: `temp-${Date.now()}`, text, completed: false },
      ]);

      // Return context for rollback
      return { previousTodos };
    },
    onError: (err, text, context) => {
      // Rollback
      queryClient.setQueryData(['todos'], context?.previousTodos);
    },
    onSettled: () => {
      // Refetch to ensure consistency
      queryClient.invalidateQueries({ queryKey: ['todos'] });
    },
  });

  const toggleMutation = useMutation({
    mutationFn: ({ id, completed }: { id: string; completed: boolean }) =>
      api.updateTodo(id, { completed }),
    onMutate: async ({ id, completed }) => {
      await queryClient.cancelQueries({ queryKey: ['todos'] });

      const previousTodos = queryClient.getQueryData(['todos']);

      queryClient.setQueryData(['todos'], (old: Todo[]) =>
        old.map(todo =>
          todo.id === id ? { ...todo, completed } : todo
        )
      );

      return { previousTodos };
    },
    onError: (err, variables, context) => {
      queryClient.setQueryData(['todos'], context?.previousTodos);
    },
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] });
    },
  });

  const deleteMutation = useMutation({
    mutationFn: (id: string) => api.deleteTodo(id),
    onMutate: async (id) => {
      await queryClient.cancelQueries({ queryKey: ['todos'] });

      const previousTodos = queryClient.getQueryData(['todos']);

      queryClient.setQueryData(['todos'], (old: Todo[]) =>
        old.filter(todo => todo.id !== id)
      );

      return { previousTodos };
    },
    onError: (err, id, context) => {
      queryClient.setQueryData(['todos'], context?.previousTodos);
    },
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] });
    },
  });

  return { addMutation, toggleMutation, deleteMutation };
}

With Zustand#

import { create } from 'zustand';
import { immer } from 'zustand/middleware/immer';

interface Todo {
  id: string;
  text: string;
  completed: boolean;
  isPending?: boolean;
}

interface TodoStore {
  todos: Todo[];
  addTodo: (text: string) => Promise<void>;
  toggleTodo: (id: string) => Promise<void>;
  deleteTodo: (id: string) => Promise<void>;
}

const useTodoStore = create<TodoStore>()(
  immer((set, get) => ({
    todos: [],

    addTodo: async (text) => {
      const tempId = `temp-${Date.now()}`;

      // Optimistic add
      set(state => {
        state.todos.push({
          id: tempId,
          text,
          completed: false,
          isPending: true,
        });
      });

      try {
        const todo = await api.createTodo(text);
        set(state => {
          const index = state.todos.findIndex(t => t.id === tempId);
          if (index !== -1) {
            state.todos[index] = { ...todo, isPending: false };
          }
        });
      } catch {
        // Rollback
        set(state => {
          state.todos = state.todos.filter(t => t.id !== tempId);
        });
      }
    },

    toggleTodo: async (id) => {
      const todo = get().todos.find(t => t.id === id);
      if (!todo) return;

      const previousCompleted = todo.completed;

      // Optimistic toggle
      set(state => {
        const t = state.todos.find(t => t.id === id);
        if (t) {
          t.completed = !t.completed;
          t.isPending = true;
        }
      });

      try {
        await api.updateTodo(id, { completed: !previousCompleted });
        set(state => {
          const t = state.todos.find(t => t.id === id);
          if (t) t.isPending = false;
        });
      } catch {
        // Rollback
        set(state => {
          const t = state.todos.find(t => t.id === id);
          if (t) {
            t.completed = previousCompleted;
            t.isPending = false;
          }
        });
      }
    },

    deleteTodo: async (id) => {
      const todos = get().todos;
      const todo = todos.find(t => t.id === id);
      const index = todos.findIndex(t => t.id === id);

      // Optimistic delete
      set(state => {
        state.todos = state.todos.filter(t => t.id !== id);
      });

      try {
        await api.deleteTodo(id);
      } catch {
        // Rollback
        set(state => {
          if (todo) {
            state.todos.splice(index, 0, todo);
          }
        });
      }
    },
  }))
);

Handling Race Conditions#

function useOptimisticUpdate<T>(
  key: string,
  fetcher: () => Promise<T>
) {
  const [data, setData] = useState<T | null>(null);
  const versionRef = useRef(0);

  const update = useCallback(async (
    optimisticData: T,
    serverUpdate: () => Promise<T>
  ) => {
    const version = ++versionRef.current;

    // Optimistic update
    setData(optimisticData);

    try {
      const result = await serverUpdate();

      // Only apply if this is still the latest update
      if (version === versionRef.current) {
        setData(result);
      }
    } catch (error) {
      // Only rollback if this is still the latest update
      if (version === versionRef.current) {
        const fresh = await fetcher();
        setData(fresh);
      }
      throw error;
    }
  }, [fetcher]);

  return { data, update };
}

Visual Feedback#

function OptimisticItem({ item, onDelete }: {
  item: Todo & { isPending?: boolean };
  onDelete: () => void;
}) {
  return (
    <div
      className={`
        item
        ${item.isPending ? 'item--pending' : ''}
      `}
    >
      <span className="item-text">{item.text}</span>

      {item.isPending && (
        <span className="item-status">
          <Spinner size="small" />
          Saving...
        </span>
      )}

      <button
        onClick={onDelete}
        disabled={item.isPending}
      >
        Delete
      </button>
    </div>
  );
}

// CSS
const styles = `
  .item {
    transition: opacity 0.2s;
  }

  .item--pending {
    opacity: 0.6;
    pointer-events: none;
  }

  .item--pending .item-text {
    font-style: italic;
  }
`;

Error Recovery UI#

function TodoWithRetry({ todo, onRetry, onDiscard }: {
  todo: Todo & { error?: Error };
  onRetry: () => void;
  onDiscard: () => void;
}) {
  if (todo.error) {
    return (
      <div className="todo todo--error">
        <span>{todo.text}</span>
        <div className="error-actions">
          <span className="error-message">
            Failed to save
          </span>
          <button onClick={onRetry}>Retry</button>
          <button onClick={onDiscard}>Discard</button>
        </div>
      </div>
    );
  }

  return (
    <div className="todo">
      <span>{todo.text}</span>
    </div>
  );
}

Best Practices#

Implementation:
✓ Use unique temporary IDs
✓ Track pending state visually
✓ Handle race conditions
✓ Provide rollback mechanism

UX:
✓ Show visual feedback for pending items
✓ Disable interactions during pending
✓ Offer retry on failure
✓ Consider undo functionality

Error Handling:
✓ Rollback on failure
✓ Show clear error messages
✓ Allow manual retry
✓ Log failures for debugging

Performance:
✓ Batch related updates
✓ Debounce rapid changes
✓ Cancel pending requests on new updates
✓ Invalidate and refetch after mutations

Optimistic updates provide instant feedback while syncing with the server. Implement proper rollback for failures, show visual feedback for pending states, and handle race conditions. Use libraries like React Query for built-in support and consistent patterns.