TanStack Virtual 3.0 Dynamic Windowing & Scroll Containment Standard

--- description: TanStack Virtual 3.0 Dynamic Windowing & Scroll Containment Standard - Enforces strict DOM node containment, element measurement caching, and continuous scroll margin preservation for massive data grids using TanStack Virtual v3. Prevents layout thrashing, DOM node saturation, and measurement jitter during high-velocity scrolling by requiring deterministic item keys, CSS contain properties, and explicit scroll margin offsets. Mandates hardware-accelerated transform positioning over direct offset mutations. globs: src/**/*.{ts,tsx}, components/**/*.{ts,tsx}, features/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-virtual-v3-performance-containment" --- # TanStack Virtual 3.0 Dynamic Windowing & Scroll Containment Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Uncached dynamic element re-measurements causing layout thrashing and DOM node explosion in continuous virtualization containers ## System Constraints You are a Principal Frontend Architect enforcing TanStack Virtual 3.0 Windowing Performance. Mandate absolute isolation of dynamic row measurements, rigid scroll-margin containment, and zero layout thrashing in virtualization viewports. Reject implementations with index-based item tracking, uncontained dynamic heights, inline resize observer attachments, or top/left absolute positioning. ## Strict Guidelines - Engineers MUST ALWAYS pass a stable, deterministic `getItemKey` function to `useVirtualizer` or `useWindowVirtualizer` (never rely on array index keys). - Engineers MUST apply `contain: strict` or `contain: layout size style` with `will-change: transform` to the inner virtual item containers to prevent layout recalculation cascading. - Engineers MUST use CSS `transform: translateY(${virtualRow.start}px)` instead of `top: ${virtualRow.start}px` to prevent render-tree layout thrashing during scroll ticks. - Components MUST attach the `measureElement` dynamic ref handler exclusively via callback refs rather than creating discrete `ResizeObserver` instances per rendered item. - Engineers MUST specify explicit `scrollMargin` and `gap` within the virtualizer options when rendering headers, footers, or margins instead of embedding manual padding within virtual calculations. - Components NEVER render unbounded overscan counts in high-frequency scroll contexts; `overscan` MUST be bounded between 3 and 12 rows to prevent DOM node saturation. - Engineers MUST configure a realistic `estimateSize` fallback close to the median dynamically measured height to eliminate scrollbar jump anomalies. ## Bad vs Good Implementations ### Dynamic Height Measurement with Containment & Translate Transform #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using array indexes for keys leads to stale measurement caches and DOM thrashing. Positioning with `top` invalidates geometry on every scroll frame. An excessive overscan of 100 defeats the memory benefits of virtualization. Omitting `measureElement` on dynamic content causes overlap and measurement jitter. ```typescript import React, { useRef } from 'react'; import { useVirtualizer } from '@tanstack/react-virtual'; interface RowData { id: string; content: string; } export function VirtualList({ items }: { items: RowData[] }) { const parentRef = useRef<HTMLDivElement>(null); // BAD: Missing getItemKey, unbounded overscan, zero estimate tuning const virtualizer = useVirtualizer({ count: items.length, getScrollElement: () => parentRef.current, estimateSize: () => 10, overscan: 100, }); return ( <div ref={parentRef} style={{ height: '600px', overflow: 'auto' }}> <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}> {virtualizer.getVirtualItems().map((virtualRow) => ( <div key={virtualRow.index} // BAD: Using array index style={{ position: 'absolute', top: `${virtualRow.start}px`, // BAD: Triggers layout recalculation on scroll left: 0, width: '100%', }} > {/* BAD: Dynamic content without measureElement ref binding */} <div style={{ padding: '8px' }}>{items[virtualRow.index].content}</div> </div> ))} </div> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Implements deterministic `getItemKey` mapped to entity IDs, binds dynamic DOM nodes via `measureElement` callback ref with `data-index`, uses `transform: translateY` for GPU-accelerated compositing, bounds `overscan` to 5 rows, and applies CSS `contain` isolation to avoid reflowing the entire document. ```typescript import React, { useRef, useCallback } from 'react'; import { useVirtualizer } from '@tanstack/react-virtual'; interface RowData { id: string; content: string; } export function VirtualList({ items }: { items: RowData[] }) { const parentRef = useRef<HTMLDivElement>(null); const getItemKey = useCallback((index: number) => items[index]?.id ?? index, [items]); const virtualizer = useVirtualizer({ count: items.length, getScrollElement: () => parentRef.current, estimateSize: () => 48, getItemKey, overscan: 5, scrollMargin: 0, }); return ( <div ref={parentRef} style={{ height: '600px', overflowY: 'auto', contain: 'strict', }} > <div style={{ height: `${virtualizer.getTotalSize()}px`, width: '100%', position: 'relative', }} > {virtualizer.getVirtualItems().map((virtualRow) => { const item = items[virtualRow.index]; return ( <div key={virtualRow.key} ref={virtualizer.measureElement} data-index={virtualRow.index} style={{ position: 'absolute', top: 0, left: 0, width: '100%', transform: `translateY(${virtualRow.start}px)`, willChange: 'transform', contain: 'layout size style', }} > <div style={{ padding: '12px', borderBottom: '1px solid #e2e8f0' }}> {item.content} </div> </div> ); })} </div> </div> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Virtual 3.0 Dynamic Windowing & Scroll Containment Standard

TanStack Virtual 3.0 Dynamic Windowing & Scroll Containment Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict DOM node containment, element measurement caching, and continuous scroll margin preservation for massive data grids using TanStack Virtual v3. Prevents layout thrashing, DOM node saturation, and measurement jitter during high-velocity scrolling by requiring deterministic item keys, CSS contain properties, and explicit scroll margin offsets. Mandates hardware-accelerated transform positioning over direct offset mutations. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Uncached dynamic element re-measurements causing layout thrashing and DOM node explosion in continuous virtualization containers Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Uncached dynamic element re-measurements causing layout thrashing and DOM node explosion in continuous virtualization containers	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS pass a stable, deterministic `getItemKey` function to `useVirtualizer` or `useWindowVirtualizer` (never rely on array index keys).

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.