name: lazy-loading
description: Use when loading all data upfront. Use when initial page load is slow. Use when fetching data that might not be needed.

Lazy Loading

Overview

Load data when needed, not before. Don't fetch what you might not use.

Upfront loading wastes bandwidth, memory, and time. Load on demand for better performance and user experience.

When to Use

• Dashboard loads all data at once
• Page fetches data for hidden tabs
• Loading "just in case" data
• Initial load is slow

The Iron Rule

NEVER load data until it's actually needed.

No exceptions:
- Not for "we might need it"
- Not for "parallel is faster"
- Not for "simpler to load everything"
- Not for "it's not that much data"

Detection: Eager Overload Smell

If you load everything upfront, STOP:

// ❌ VIOLATION: Load everything upfront
async function loadDashboard(userId: string) {
  const [
    profile,
    preferences,
    notifications,    // User might not check
    recentActivity,   // Collapsed by default
    analytics,        // Expensive, rarely viewed
    recommendations,  // Below the fold
    fullHistory       // Paginated anyway
  ] = await Promise.all([
    fetchProfile(userId),
    fetchPreferences(userId),
    fetchNotifications(userId),
    fetchRecentActivity(userId),
    fetchAnalytics(userId),       // Takes 2 seconds!
    fetchRecommendations(userId),
    fetchFullHistory(userId)      // 10MB of data!
  ]);

  return { profile, preferences, notifications, ... };
}

Problems:
- Slowest fetch blocks everything
- Wastes resources on unused data
- Poor perceived performance

The Correct Pattern: Load On Demand

// ✅ CORRECT: Load critical data first, rest on demand

// Initial load - only what's immediately visible
async function loadDashboard(userId: string) {
  const [profile, preferences] = await Promise.all([
    fetchProfile(userId),
    fetchPreferences(userId)
  ]);

  return { profile, preferences };
}

// React component with lazy loading
function Dashboard({ userId }) {
  // Critical data loaded immediately
  const { profile, preferences } = useInitialData(userId);

  // Notifications: load when header mounts
  const notifications = useLazyQuery(
    () => fetchNotifications(userId),
    { loadOn: 'mount' }
  );

  // Analytics: load when tab is selected
  const [analyticsTab, setAnalyticsTab] = useState(false);
  const analytics = useLazyQuery(
    () => fetchAnalytics(userId),
    { loadOn: analyticsTab }
  );

  // History: load when scrolled into view
  const historyRef = useRef();
  const history = useLazyQuery(
    () => fetchHistory(userId),
    { loadOn: useIntersectionObserver(historyRef) }
  );

  return (
    <div>
      <Header profile={profile} notifications={notifications} />
      <Tabs>
        <Tab label="Overview">...</Tab>
        <Tab label="Analytics" onSelect={() => setAnalyticsTab(true)}>
          {analytics.loading ? <Skeleton /> : <AnalyticsChart data={analytics.data} />}
        </Tab>
      </Tabs>
      <div ref={historyRef}>
        {history.data && <HistoryList items={history.data} />}
      </div>
    </div>
  );
}

Lazy Loading Techniques

1. Load on Interaction

// Load when user clicks tab
const [showDetails, setShowDetails] = useState(false);
const details = useQuery(fetchDetails, { enabled: showDetails });

<Tab onClick={() => setShowDetails(true)}>
  {details.data ?? <Skeleton />}
</Tab>

2. Load on Scroll (Intersection Observer)

function LazySection({ loadFn, children }) {
  const ref = useRef();
  const [loaded, setLoaded] = useState(false);
  const data = useQuery(loadFn, { enabled: loaded });

  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => entry.isIntersecting && setLoaded(true)
    );
    observer.observe(ref.current);
    return () => observer.disconnect();
  }, []);

  return <div ref={ref}>{data.data ? children(data.data) : <Skeleton />}</div>;
}

3. Load on Route

// Next.js / React Router
const AnalyticsPage = lazy(() => import('./AnalyticsPage'));

<Route path="/analytics" element={
  <Suspense fallback={<Loading />}>
    <AnalyticsPage />
  </Suspense>
} />

4. Pagination / Infinite Scroll

function OrderList() {
  const [page, setPage] = useState(1);
  const { data, hasMore } = useOrders({ page, limit: 20 });

  return (
    <>
      {data.map(order => <OrderRow key={order.id} order={order} />)}
      {hasMore && <button onClick={() => setPage(p => p + 1)}>Load More</button>}
    </>
  );
}

Pressure Resistance Protocol

1. "We Might Need It"

Pressure: "Load it now in case user needs it"

Response: "Might" means probably won't. Load when they actually need it.

Action: Load on demand, not on speculation.

2. "Parallel Is Faster"

Pressure: "Loading everything in parallel is faster than sequential"

Response: Parallel loading of unneeded data is slower than not loading it.

Action: Parallelize what you need. Lazy load what you might need.

3. "Simpler to Load Everything"

Pressure: "One fetch function is simpler"

Response: Simple code that's slow and wasteful isn't simple.

Action: Structured lazy loading is maintainable and performant.

Red Flags - STOP and Reconsider

• Promise.all with 5+ fetches on page load
• Fetching data for collapsed/hidden sections
• Loading full lists instead of paginating
• Slow initial page loads
• "Loading..." takes more than 1-2 seconds

All of these mean: Implement lazy loading.

Quick Reference

Common Rationalizations (All Invalid)

The Bottom Line

Load what's visible. Defer the rest. Paginate large lists.

Initial load = critical data only. Everything else loads on interaction, scroll, or navigation. Users shouldn't wait for data they won't see.