System Design: Design an Infinite Scroller — The Component That Broke (and Fixed) the Web

// ❌ The approach that kills your app
function NaiveFeed() {
  const [items, setItems] = useState<Item[]>([]);
  
  useEffect(() => {
    const observer = new IntersectionObserver(([entry]) => {
      if (entry.isIntersecting) loadMore();
    });
    observer.observe(sentinelRef.current!);
  }, []);

  return (
    <div>
      {items.map(item => <FeedItem key={item.id} item={item} />)}
      <div ref={sentinelRef} />
    </div>
  );
}

// ✅ Only render what is visible
function VirtualizedFeed() {
  // Only items in viewport + buffer are in the DOM
  // Everything else is represented by empty space (padding)
  
  return (
    <div style={{ height: totalHeight }}>
      <div style={{ transform: \`translateY(${offsetTop}px)\` }}>
        {visibleItems.map(item => (
          <FeedItem key={item.id} item={item} />
        ))}
      </div>
    </div>
  );
}

/* 🆕 CSS-based virtualization — no JS needed */
.feed-item {
  content-visibility: auto;
  contain-intrinsic-size: 0 400px; /* Estimated height */
}

InfiniteScrollContainer
├── ScrollSentinel (top — for bidirectional/pull-to-refresh)
├── VirtualizedList
│   ├── HeightEstimator (pre-computes heights from metadata)
│   ├── ScrollPositionManager (saves/restores scroll state)
│   ├── VisibleWindow
│   │   ├── ListItem (measured with ResizeObserver)
│   │   ├── ListItem
│   │   └── ...
│   ├── PaddingTop (represents items above viewport)
│   └── PaddingBottom (represents items below viewport)
├── ScrollSentinel (bottom — triggers next page fetch)
├── LoadingIndicator (skeleton placeholders)
├── ErrorBoundary (retry on failed fetches)
├── EndOfListMarker ("You have reached the end")
└── ScrollToTop (floating button)

Supporting Infrastructure:
├── IntersectionObserverManager (shared observer instance)
├── HeightCache (persists measured heights across sessions)
├── PrefetchController (predictive page loading)
└── FocusManager (keyboard navigation for virtualized items)

interface InfiniteScrollStore {
  // === Item data ===
  items: Map<string, ListItem>;      // Normalized by ID
  orderedIds: string[];               // Maintains insertion order
  
  // === Pagination state ===
  pagination: {
    nextCursor: string | null;
    prevCursor: string | null;        // For bidirectional scrolling
    hasMore: boolean;
    hasPrevious: boolean;
    isLoadingNext: boolean;
    isLoadingPrevious: boolean;
    error: Error | null;
    retryCount: number;
    totalEstimate: number | null;     // Server-provided total count estimate
  };
  
  // === Measurement cache ===
  measurements: {
    heights: Map<string, number>;     // Measured heights per item
    estimatedItemHeight: number;      // Running average for unmeasured items
    totalMeasuredHeight: number;
    measuredCount: number;
  };
  
  // === Viewport state ===
  viewport: {
    scrollTop: number;
    viewportHeight: number;
    overscan: number;                 // Buffer items above/below viewport
    visibleRange: { start: number; end: number };
    anchorItem: {
      id: string;
      offsetFromTop: number;
    } | null;
  };
  
  // === Scroll restoration ===
  savedPositions: Map<string, {
    scrollTop: number;
    anchorItemId: string;
    anchorOffset: number;
    orderedIds: string[];
    heights: Map<string, number>;
  }>;
}

interface ListItem {
  id: string;
  data: unknown;
  estimatedHeight?: number;
  mediaAspectRatio?: number;
  hasExpandableContent?: boolean;
  contentType: string;
}

class HeightEstimator {
  private measuredHeights = new Map<string, number>();
  private heightsByType = new Map<string, number[]>();
  private defaultEstimate = 400;
  
  recordHeight(itemId: string, height: number, contentType: string) {
    this.measuredHeights.set(itemId, height);
    const typeHeights = this.heightsByType.get(contentType) || [];
    typeHeights.push(height);
    this.heightsByType.set(contentType, typeHeights);
  }
  
  getHeight(item: ListItem): number {
    // 1. Real measurement
    const measured = this.measuredHeights.get(item.id);
    if (measured !== undefined) return measured;
    
    // 2. Server-provided estimate
    if (item.estimatedHeight) return item.estimatedHeight;
    
    // 3. Content-type median
    const typeHeights = this.heightsByType.get(item.contentType);
    if (typeHeights && typeHeights.length > 5) {
      return this.median(typeHeights);
    }
    
    // 4. Default
    return this.defaultEstimate;
  }
  
  getVisibleRange(
    items: ListItem[], 
    scrollTop: number, 
    viewportHeight: number,
    overscan: number = 3
  ): { start: number; end: number; offsetTop: number } {
    let accumulatedHeight = 0;
    let start = 0;
    let end = items.length;
    let offsetTop = 0;
    
    for (let i = 0; i < items.length; i++) {
      const itemHeight = this.getHeight(items[i]);
      if (accumulatedHeight + itemHeight > scrollTop) {
        start = Math.max(0, i - overscan);
        offsetTop = accumulatedHeight;
        break;
      }
      accumulatedHeight += itemHeight;
    }
    
    const viewportBottom = scrollTop + viewportHeight;
    for (let i = start; i < items.length; i++) {
      accumulatedHeight += this.getHeight(items[i]);
      if (accumulatedHeight > viewportBottom) {
        end = Math.min(items.length, i + overscan + 1);
        break;
      }
    }
    
    return { start, end, offsetTop };
  }
  
  private median(arr: number[]): number {
    const sorted = [...arr].sort((a, b) => a - b);
    const mid = Math.floor(sorted.length / 2);
    return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
  }
}

interface UseInfiniteScrollOptions<T> {
  fetchPage: (cursor: string | null) => Promise<{
    items: T[];
    nextCursor: string | null;
    hasMore: boolean;
  }>;
  getItemId: (item: T) => string;
  getItemType?: (item: T) => string;
  estimateItemHeight?: (item: T) => number;
  overscan?: number;
  threshold?: number;
  prefetchThreshold?: number;
  scrollRestorationKey?: string;
  onError?: (error: Error) => void;
}

interface UseInfiniteScrollReturn<T> {
  items: T[];
  visibleRange: { start: number; end: number };
  totalHeight: number;
  offsetTop: number;
  isLoading: boolean;
  isLoadingMore: boolean;
  error: Error | null;
  hasMore: boolean;
  isEmpty: boolean;
  refresh: () => Promise<void>;
  retry: () => Promise<void>;
  scrollToItem: (id: string, behavior?: ScrollBehavior) => void;
  scrollToTop: (behavior?: ScrollBehavior) => void;
  containerRef: React.RefObject<HTMLDivElement>;
  measureRef: (id: string) => (node: HTMLElement | null) => void;
}

// Usage example
function SocialFeed() {
  const {
    items, visibleRange, totalHeight, offsetTop,
    isLoadingMore, hasMore, containerRef, measureRef,
    refresh, scrollToTop
  } = useInfiniteScroll<Post>({
    fetchPage: async (cursor) => {
      const res = await api.get("/feed", { cursor, limit: 10 });
      return { items: res.posts, nextCursor: res.nextCursor, hasMore: res.hasMore };
    },
    getItemId: (post) => post.id,
    getItemType: (post) => post.mediaType,
    estimateItemHeight: (post) => {
      const BASE = 120;
      return BASE + (window.innerWidth / (post.aspectRatio || 1));
    },
    scrollRestorationKey: "home-feed",
    threshold: 1000,
    prefetchThreshold: 2000,
  });

  return (
    <div ref={containerRef} className="overflow-auto h-screen">
      <PullToRefresh onRefresh={refresh}>
        <div style={{ height: totalHeight, position: "relative" }}>
          <div style={{ transform: \`translateY(${offsetTop}px)\` }}>
            {items.slice(visibleRange.start, visibleRange.end).map(post => (
              <div key={post.id} ref={measureRef(post.id)}>
                <FeedPost post={post} />
              </div>
            ))}
          </div>
        </div>
        {isLoadingMore && <LoadingSkeleton count={3} />}
        {!hasMore && <EndOfFeed />}
      </PullToRefresh>
      <ScrollToTopButton onClick={() => scrollToTop("smooth")} />
    </div>
  );
}

// Throttled to rAF for 60fps
useEffect(() => {
  const container = containerRef.current;
  if (!container) return;

  let ticking = false;
  
  const onScroll = () => {
    if (!ticking) {
      requestAnimationFrame(() => {
        const { scrollTop, scrollHeight, clientHeight } = container;
        const distanceFromBottom = scrollHeight - scrollTop - clientHeight;
        
        // Update visible range
        recalculateVisibleRange();
        
        // Trigger fetch near bottom
        if (distanceFromBottom < threshold && hasMore && !isLoadingMore) {
          loadNextPage();
        }
        
        // Prefetch when approaching
        if (distanceFromBottom < prefetchThreshold && !prefetchedRef.current) {
          prefetchNextPage();
        }
        
        // Save position for restoration
        if (scrollRestorationKey) saveScrollPosition(scrollTop);
        
        ticking = false;
      });
      ticking = true;
    }
  };

  container.addEventListener("scroll", onScroll, { passive: true });
  return () => container.removeEventListener("scroll", onScroll);
}, [hasMore, isLoadingMore]);

class ScrollRestorationManager {
  private cache = new Map<string, SavedScrollState>();
  
  save(key: string, state: InfiniteScrollStore) {
    this.cache.set(key, {
      scrollTop: state.viewport.scrollTop,
      anchor: {
        itemId: this.findAnchorItem(state),
        offsetFromViewportTop: this.getAnchorOffset(state),
      },
      itemIds: state.orderedIds.slice(0, state.viewport.visibleRange.end + 20),
      heights: new Map(state.measurements.heights),
      timestamp: Date.now(),
    });
  }
  
  async restore(
    key: string, 
    container: HTMLElement,
    fetchItems: (ids: string[]) => Promise<ListItem[]>
  ): Promise<boolean> {
    const saved = this.cache.get(key);
    if (!saved || Date.now() - saved.timestamp > 5 * 60 * 1000) {
      return false; // Cache expired
    }
    
    const items = await fetchItems(saved.itemIds);
    
    // Restore height measurements
    for (const [id, height] of saved.heights) {
      heightEstimator.recordHeight(id, height, "cached");
    }
    
    // Calculate scroll position from anchor
    const anchorIndex = items.findIndex(i => i.id === saved.anchor.itemId);
    if (anchorIndex === -1) return false;
    
    let scrollTop = 0;
    for (let i = 0; i < anchorIndex; i++) {
      scrollTop += heightEstimator.getHeight(items[i]);
    }
    scrollTop -= saved.anchor.offsetFromViewportTop;
    
    requestAnimationFrame(() => {
      container.scrollTop = scrollTop;
    });
    
    return true;
  }
}

class PrefetchController {
  private prefetchCache = new Map<string, Promise<PageResponse>>();
  private scrollVelocity = 0;
  private lastScrollTop = 0;
  private lastScrollTime = 0;
  
  updateScrollMetrics(scrollTop: number) {
    const now = performance.now();
    const dt = now - this.lastScrollTime;
    if (dt > 0) {
      this.scrollVelocity = (scrollTop - this.lastScrollTop) / dt;
    }
    this.lastScrollTop = scrollTop;
    this.lastScrollTime = now;
  }
  
  shouldPrefetch(distanceFromBottom: number): boolean {
    const velocityThreshold = this.scrollVelocity > 2 
      ? 3000  // Fast scroll: prefetch 3 screens away
      : 1500; // Normal: 1.5 screens away
    return distanceFromBottom < velocityThreshold;
  }
  
  async prefetch(cursor: string, fetchFn: FetchFn): Promise<PageResponse> {
    if (this.prefetchCache.has(cursor)) {
      return this.prefetchCache.get(cursor)!;
    }
    const promise = fetchFn(cursor);
    this.prefetchCache.set(cursor, promise);
    if (this.prefetchCache.size > 3) {
      const oldestKey = this.prefetchCache.keys().next().value;
      this.prefetchCache.delete(oldestKey);
    }
    return promise;
  }
}

class BidirectionalScroller {
  async prependItems(newItems: ListItem[], container: HTMLElement) {
    // Step 1: Record current anchor
    const firstVisible = this.getFirstVisibleItem();
    const anchorOffset = firstVisible.element.getBoundingClientRect().top;
    
    // Step 2: Insert items into DOM
    this.insertAtTop(newItems);
    
    // Step 3: Measure height of new items
    const addedHeight = newItems.reduce((sum, item) => {
      return sum + this.measureItem(item);
    }, 0);
    
    // Step 4: Adjust scroll position to maintain visual anchor
    // This must happen synchronously before the browser paints
    container.scrollTop += addedHeight;
    
    // Step 5: Fine-tune
    const newOffset = firstVisible.element.getBoundingClientRect().top;
    if (Math.abs(newOffset - anchorOffset) > 1) {
      container.scrollTop += (anchorOffset - newOffset);
    }
  }
}

// Modern CSS approach: overflow-anchor: auto;
// But it does not work reliably with virtualized lists.
// So you need the manual approach above for production.

// 1. CSS contain for layout isolation
const itemStyle = {
  contain: "layout style paint",
  willChange: "transform",
};

// 2. Batched ResizeObserver
class BatchedResizeObserver {
  private pendingUpdates = new Map<string, number>();
  private rafId: number | null = null;
  private observer: ResizeObserver;
  
  constructor(private onBatchComplete: (updates: Map<string, number>) => void) {
    this.observer = new ResizeObserver((entries) => {
      for (const entry of entries) {
        const id = entry.target.getAttribute("data-item-id")!;
        const height = entry.borderBoxSize[0]?.blockSize ?? entry.contentRect.height;
        this.pendingUpdates.set(id, height);
      }
      if (!this.rafId) {
        this.rafId = requestAnimationFrame(() => {
          this.onBatchComplete(new Map(this.pendingUpdates));
          this.pendingUpdates.clear();
          this.rafId = null;
        });
      }
    });
  }
}

// 3. Passive scroll listeners
container.addEventListener("scroll", onScroll, { passive: true });

// 4. Avoid layout thrashing — batch reads and writes
function recalculateVisibleRange() {
  // READ phase
  const scrollTop = container.scrollTop;
  const viewportHeight = container.clientHeight;
  
  // COMPUTE phase — no DOM access
  const { start, end, offsetTop } = heightEstimator.getVisibleRange(
    items, scrollTop, viewportHeight, overscan
  );
  
  // WRITE phase — via state update
  dispatch({ type: "SET_VISIBLE_RANGE", start, end, offsetTop });
}

function AccessibleVirtualList({ items, visibleRange, totalCount }: Props) {
  const [focusedIndex, setFocusedIndex] = useState(-1);
  const announcerRef = useRef<HTMLDivElement>(null);
  
  const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
    switch (e.key) {
      case "ArrowDown":
        e.preventDefault();
        const nextIndex = Math.min(focusedIndex + 1, items.length - 1);
        setFocusedIndex(nextIndex);
        if (nextIndex >= visibleRange.end) {
          scrollToItem(items[nextIndex].id, "smooth");
          requestAnimationFrame(() => {
            const el = document.querySelector(\`[data-item-index="${nextIndex}"]\`);
            (el as HTMLElement)?.focus();
          });
        }
        break;
      case "ArrowUp":
        e.preventDefault();
        const prevIndex = Math.max(focusedIndex - 1, 0);
        setFocusedIndex(prevIndex);
        if (prevIndex < visibleRange.start) {
          scrollToItem(items[prevIndex].id, "smooth");
        }
        break;
    }
  }, [focusedIndex, visibleRange]);

  return (
    <div role="feed" aria-label="Content feed" aria-busy={isLoading} onKeyDown={handleKeyDown}>
      <div ref={announcerRef} aria-live="polite" aria-atomic="false" className="sr-only" />
      {items.slice(visibleRange.start, visibleRange.end).map((item, i) => {
        const absoluteIndex = visibleRange.start + i;
        return (
          <article
            key={item.id}
            role="article"
            tabIndex={absoluteIndex === focusedIndex ? 0 : -1}
            aria-setsize={totalCount || -1}
            aria-posinset={absoluteIndex + 1}
            data-item-index={absoluteIndex}
          >
            <ListItemContent item={item} />
          </article>
        );
      })}
    </div>
  );
}

class MemoryManager {
  private maxCachedItems = 500;
  
  evictDistantItems(store: InfiniteScrollStore, currentCenter: number): void {
    if (store.orderedIds.length <= this.maxCachedItems) return;
    
    const keepRange = 200;
    const centerIndex = this.findIndexAtOffset(currentCenter, store);
    const keepStart = Math.max(0, centerIndex - keepRange);
    const keepEnd = Math.min(store.orderedIds.length, centerIndex + keepRange);
    
    const idsToRemove = [
      ...store.orderedIds.slice(0, keepStart),
      ...store.orderedIds.slice(keepEnd),
    ];
    
    for (const id of idsToRemove) {
      const item = store.items.get(id);
      if (item?.objectUrl) URL.revokeObjectURL(item.objectUrl);
      store.items.delete(id);
    }
  }
}