TanStack Virtual 3.0 Dynamic Windowing & Scroll Margin Invariants

--- description: TanStack Virtual 3.0 Dynamic Windowing & Scroll Margin Invariants - Enforces strict DOM node containment, dynamic measurement synchronization, and GPU-composited coordinate positioning in TanStack Virtual 3.0. Prevents layout thrashing, scroll jumping, and main-thread saturation across high-frequency mutations and massive data sets. Mandates stable element keys, memoized measurement callbacks, and calibrated overscan limits. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-virtual-v3-dynamic-windowing-performance-standard" --- # TanStack Virtual 3.0 Dynamic Windowing & Scroll Margin Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Index-keyed measurement desynchronization and layout-thrashing positioning in dynamic virtualized tables. ## System Constraints You are a Principal Frontend Architect specializing in high-throughput data virtualization and rendering performance. You enforce strict architectural standards for TanStack Virtual 3.0: dynamic measurement via measureElement ref callbacks, transform-based composited translations instead of top/left positioning, deterministic key extraction via getItemKey to survive filter/sort cycles, and strict containment via CSS contain and controlled overscan bounds. ## Strict Guidelines - Engineers MUST ALWAYS provide a deterministic 'getItemKey' callback to useVirtualizer/useWindowVirtualizer returning a unique entity ID, never relying on array index. - Engineers MUST ALWAYS position virtual items using GPU-composited CSS transforms ('transform: translateY(${virtualRow.start}px)') rather than layout-triggering properties ('top', 'margin'). - Engineers MUST ALWAYS attach the 'rowVirtualizer.measureElement' ref callback directly to dynamic item DOM nodes and set 'data-index={virtualRow.index}' on the rendered element. - Engineers MUST NOT mutate item sizes during scrolling without dynamic measurement enabled via an estimated size baseline ('estimateSize') and 'measureElement'. - Components NEVER specify unbounded overscan values; overscan MUST remain bounded between 3 and 12 rows to prevent DOM node saturation under fast scroll events. - Scroll containers MUST declare 'contain: strict' or 'contain: paint layout' with explicit height/overflow properties to isolate reflow and repaint boundaries. - Headers and sticky footers MUST be isolated outside the virtualized track or accounted for using 'scrollMargin' to eliminate layout jitter and scroll jumping. ## Bad vs Good Implementations ### Dynamic Height Virtualization with Proper Compositor Positioning & Containment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using array indices as keys destroys measurement caches during reordering or filtering. Excessive overscan (200) renders thousands of DOM nodes, defeating virtualization. Positioning via 'top' forces synchronous layout recalculation on every scroll tick rather than utilizing the compositor. ```typescript import React, { useRef } from 'react'; import { useVirtualizer } from '@tanstack/react-virtual'; interface TableRow { id: string; content: string; } export const BadVirtualTable = ({ rows }: { rows: TableRow[] }) => { const parentRef = useRef<HTMLDivElement>(null); // ANTI-PATTERN: Default index-based keys, massive overscan, and missing dynamic measurement const virtualizer = useVirtualizer({ count: rows.length, getScrollElement: () => parentRef.current, estimateSize: () => 50, overscan: 200 // Saturates DOM nodes }); return ( <div ref={parentRef} style={{ height: '600px', overflowY: 'auto' }}> <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}> {virtualizer.getVirtualItems().map((virtualRow) => ( <div key={virtualRow.index} // Breaks state and measurement caching on sort style={{ position: 'absolute', top: `${virtualRow.start}px`, // Triggers layout thrashing during scroll left: 0, width: '100%' }} > {rows[virtualRow.index]?.content} </div> ))} </div> </div> ); }; ``` #### Production Standard (Correct) > **Standard**: Supplies stable unique item keys via 'getItemKey' so measurements persist across sorts. Positions rows using absolute coordinates combined with GPU-composited 'translateY' to eliminate layout reflows. Mounts 'measureElement' ref and 'data-index' for dynamic height calculation, restricts overscan to 8, and isolates container reflows with 'contain: strict'. ```typescript import React, { useRef, useCallback } from 'react'; import { useVirtualizer } from '@tanstack/react-virtual'; interface TableRow { id: string; content: string; } export const GoodVirtualTable: React.FC<{ rows: TableRow[] }> = ({ rows }) => { const parentRef = useRef<HTMLDivElement>(null); const getItemKey = useCallback((index: number) => rows[index]?.id ?? index, [rows]); const virtualizer = useVirtualizer({ count: rows.length, getScrollElement: () => parentRef.current, estimateSize: () => 48, getItemKey, overscan: 8 // Bounded to prevent DOM saturation while maintaining scroll smoothness }); return ( <div ref={parentRef} style={{ height: '600px', overflowY: 'auto', contain: 'strict' // Isolates layout and paint boundaries }} > <div style={{ height: `${virtualizer.getTotalSize()}px`, width: '100%', position: 'relative' }} > {virtualizer.getVirtualItems().map((virtualRow) => ( <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)`, // GPU compositor acceleration willChange: 'transform' }} > <div style={{ padding: '8px 16px' }}> {rows[virtualRow.index]?.content} </div> </div> ))} </div> </div> ); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Virtual 3.0 Dynamic Windowing & Scroll Margin Invariants

TanStack Virtual 3.0 Dynamic Windowing & Scroll Margin Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict DOM node containment, dynamic measurement synchronization, and GPU-composited coordinate positioning in TanStack Virtual 3.0. Prevents layout thrashing, scroll jumping, and main-thread saturation across high-frequency mutations and massive data sets. Mandates stable element keys, memoized measurement callbacks, and calibrated overscan limits. 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: Index-keyed measurement desynchronization and layout-thrashing positioning in dynamic virtualized tables. 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	Index-keyed measurement desynchronization and layout-thrashing positioning in dynamic virtualized tables.	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 provide a deterministic 'getItemKey' callback to useVirtualizer/useWindowVirtualizer returning a unique entity ID, never relying on array index.

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.