React Preferences Persistence Pattern

Problem

User preferences are successfully saved to the database and loaded into React state, but they're not applied to the UI after page reload. Settings appear correct in the database but the UI shows default values or doesn't reflect the saved preferences.

Common symptoms:

•Accessibility settings (high contrast, font size) not applied on page load
•Theme preferences revert to default despite being saved
•Language/locale settings don't persist across page reloads
•E2E tests fail when verifying settings persistence

Context / Trigger Conditions

When this occurs:

•After implementing user preferences with database persistence
•Settings save successfully but don't apply after page refresh
•React state shows correct values but DOM doesn't reflect them
•useEffect loads data but UI remains unchanged

Typical scenario:

typescript

// ❌ BROKEN: Loads settings but never applies them to DOM
useEffect(() => {
  loadSettings(); // Updates state but DOM stays default
}, [loadSettings]);

Error manifestations:

•E2E test failures: "Expected element to have class 'high-contrast' but received ''"
•Visual regression: UI always shows defaults despite database containing preferences
•User complaints: "My settings don't save"

Solution

Pattern: Separate Loading and Application Effects

Use two distinct useEffect hooks:

•Loading Effect: Fetch data from database/API and update state
•Application Effect: Apply state changes to DOM, triggered by state changes

typescript

const [settings, setSettings] = useState({
  highContrast: false,
  fontSize: "base",
  reduceMotion: false,
});
const [loading, setLoading] = useState(true);

// Effect 1: Load settings from database
useEffect(() => {
  const loadSettings = async () => {
    setLoading(true);
    try {
      const result = await getAccessibilitySettings();
      if (result.success) {
        setSettings(result.settings);
      }
    } finally {
      setLoading(false);
    }
  };
  loadSettings();
}, []);

// Effect 2: Apply settings to DOM whenever they change
useEffect(() => {
  if (!loading) {
    applyAccessibilitySettings(settings);
  }
}, [settings, loading]);

Why This Works

•Initial Load: First effect fetches from database, updates state
•State Change Trigger: When setSettings() updates state, second effect runs
•Loading Guard: if (!loading) prevents applying default values before load completes
•Save Trigger: When user clicks save, state updates trigger application automatically

Complete Implementation

typescript

"use client";

import { useState, useEffect, useCallback } from "react";

export function AccessibilitySettings() {
  const [settings, setSettings] = useState({
    highContrast: false,
    fontSize: "base" as "sm" | "base" | "lg" | "xl",
    reduceMotion: false,
  });
  const [loading, setLoading] = useState(true);
  const [saving, setSaving] = useState(false);

  // Load settings from database
  const loadSettings = useCallback(async () => {
    setLoading(true);
    try {
      const result = await getAccessibilitySettings();
      if (result.success) {
        setSettings(result.settings);
      }
    } finally {
      setLoading(false);
    }
  }, []);

  useEffect(() => {
    loadSettings();
  }, [loadSettings]);

  // Apply settings to DOM whenever they change (after load or after save)
  useEffect(() => {
    if (!loading) {
      applyAccessibilitySettings(settings);
    }
  }, [settings, loading]);

  const handleSave = async () => {
    setSaving(true);
    try {
      const result = await updateAccessibilitySettings(settings);
      if (result.success) {
        // Settings already in state, application effect will trigger automatically
        toast.success("Settings updated");
      }
    } finally {
      setSaving(false);
    }
  };

  const applyAccessibilitySettings = (settings: typeof settings) => {
    const root = document.documentElement;

    // High contrast
    if (settings.highContrast) {
      root.classList.add("high-contrast");
    } else {
      root.classList.remove("high-contrast");
    }

    // Font size
    root.classList.remove("font-size-sm", "font-size-base", "font-size-lg", "font-size-xl");
    if (settings.fontSize !== "base") {
      root.classList.add(`font-size-${settings.fontSize}`);
    }

    // Reduce motion
    if (settings.reduceMotion) {
      root.classList.add("reduce-motion");
    } else {
      root.classList.remove("reduce-motion");
    }
  };

  if (loading) {
    return <LoadingSpinner />;
  }

  return (
    <div>
      {/* Settings UI */}
      <Button onClick={handleSave} disabled={saving}>
        Save
      </Button>
    </div>
  );
}

Verification

Manual Testing

•Change a setting and save
•Refresh the page
•Setting should be applied immediately (not defaults)
•Check browser DevTools: document.documentElement.className should show applied classes

E2E Test Pattern

typescript

test('should preserve accessibility settings after page reload', async ({ page }) => {
  // Enable high contrast
  const highContrastSwitch = page.locator('button[role="switch"]#highContrast');
  await highContrastSwitch.click();

  // Save
  const saveButton = page.locator('button').filter({ hasText: /save/i });
  await saveButton.click();

  // Wait for save to complete
  await page.waitForTimeout(1000);

  // Reload page
  await page.reload();
  await page.waitForLoadState('networkidle');

  // Verify setting persisted
  const html = page.locator('html');
  await expect(html).toHaveClass(/high-contrast/);

  // Verify switch state
  const reloadedSwitch = page.locator('button[role="switch"]#highContrast');
  await expect(reloadedSwitch).toHaveAttribute('aria-checked', 'true');
});

Example: Language/Locale Switching

For preferences that require page navigation (like language/locale changes):

typescript

const handleSave = async () => {
  setSaving(true);
  try {
    const result = await updateLanguage({ locale: selectedLocale });
    if (result.success) {
      toast.success("Language updated");
      // Navigate to new locale URL with full page reload
      const segments = window.location.pathname.split('/');
      segments[1] = selectedLocale; // Replace locale (first segment after /)
      const newPath = segments.join('/');
      window.location.href = newPath; // Full reload ensures all i18n updates
    }
  } catch (error) {
    toast.error("Failed to update language");
    setSaving(false);
  }
};

Why window.location.href?

•next-intl router's push() with { locale } parameter doesn't reliably trigger navigation
•Full page reload ensures all i18n contexts update properly
•Server components re-render with new locale
•Middleware applies correct locale prefix

Notes

Best Practices from React Docs

•
You Might Not Need an Effect: If you can calculate something during render, you don't need an Effect. Use Effects only for synchronizing with external systems (database, DOM, browser APIs).
•
Loading State Guards: Always check loading state before applying DOM changes to prevent flicker from default → loaded values.
•
Cleanup Functions: For event listeners or subscriptions, return cleanup functions from useEffect to prevent memory leaks.
•
Dependencies: Include all reactive values used inside the effect in the dependency array (or use useCallback for functions).

Common Mistakes

❌ Applying settings only on save (missing the load → apply path):

typescript

const handleSave = async () => {
  await updateSettings(settings);
  applySettings(settings); // ❌ Only applies when user clicks save
};

❌ Single effect for load + apply (race condition with async load):

typescript

useEffect(() => {
  loadSettings(); // async
  applySettings(settings); // ❌ Runs before load completes, uses defaults
}, []);

✅ Separate effects with loading guard:

typescript

useEffect(() => {
  loadSettings();
}, []);

useEffect(() => {
  if (!loading) applySettings(settings); // ✅ Waits for load
}, [settings, loading]);

react-preferences-persistence-pattern

React Preferences Persistence Pattern

Problem

Context / Trigger Conditions

Solution

Pattern: Separate Loading and Application Effects

Why This Works

Complete Implementation

Verification

Manual Testing

E2E Test Pattern

Example: Language/Locale Switching

Notes

Best Practices from React Docs

Common Mistakes

When to Use This Pattern

When NOT to Use This Pattern

References