TanStack Virtual 3.0 Dynamic Windowing and Containment Standard

--- description: TanStack Virtual 3.0 Dynamic Windowing and Containment Standard - Enforces strict virtual DOM containment, hardware-accelerated transform positioning, and deterministic measurement caching for TanStack Virtual 3.0. Prevents layout thrashing, DOM node saturation, and measurement cache eviction in high-frequency, dynamic-height tabular datasets. 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-standard" --- # TanStack Virtual 3.0 Dynamic Windowing and Containment Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Dynamic element measurement without data-index anchors, unmemoized getItemKey, and missing CSS layout containment causing catastrophic reflow loops. ## System Constraints You are a Principal Frontend Performance Architect enforcing TanStack Virtual 3.0 windowing invariants. Mandate strict layout containment, deterministic keying, dynamic size caching via data-index attributes, and GPU-accelerated spatial offsets to prevent DOM node saturation and browser thread freezing. ## Strict Guidelines - Components measuring dynamic row heights MUST attach 'ref={virtualizer.measureElement}' directly to the rendered node and specify 'data-index={virtualRow.index}' on that exact element. - Engineers MUST provide a stable, unique 'getItemKey' function to 'useVirtualizer'; falling back to default row indices causes measurement cache invalidation upon sorting or filtering. - Scroll containers MUST apply CSS containment ('contain: strict' or 'contain: layout size') and explicit 'overflow: auto' to isolate sub-tree reflows from the rest of the document. - Engineers MUST NOT position virtualized items using 'top' or 'margin-top'; all spatial positioning MUST use hardware-accelerated 'transform: translateY(${virtualRow.start}px)'. - Virtualizers MUST restrict 'overscan' to safe thresholds (between 3 and 8 rows); never set overscan excessively high (> 15) in massive tables as it compromises DOM node pruning. - Virtual item containers MUST maintain total scroll height using an outer element sized with 'virtualizer.getTotalSize()' and 'position: relative', while items inside use 'position: absolute'. ## Bad vs Good Implementations ### Dynamic Element Measurement & Containment in TanStack Virtual 3.0 #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting 'getItemKey' forces index-based identity, which corrupts size measurements on collection mutation. Positioning using 'top' instead of CSS transforms triggers the browser layout engine on every frame. Omitting 'data-index' prevents TanStack Virtual's dynamic element measurement from resolving accurate indices. An overscan of 50 over-allocates DOM nodes, defeating windowing objectives. ```typescript import React, { useRef } from 'react'; import { useVirtualizer } from '@tanstack/react-virtual'; interface RowData { id: string; content: string; } export const BadVirtualList: React.FC<{ items: RowData[] }> = ({ items }) => { const parentRef = useRef<HTMLDivElement>(null); // ANTI-PATTERN: Missing getItemKey causes cache drops on sort/filter. // Overscan of 50 saturates the DOM. const virtualizer = useVirtualizer({ count: items.length, getScrollElement: () => parentRef.current, estimateSize: () => 50, overscan: 50, }); return ( // ANTI-PATTERN: Missing CSS containment leads to global document reflows <div ref={parentRef} style={{ height: '600px', overflowY: 'scroll' }}> <div style={{ height: `${virtualizer.getTotalSize()}px`, width: '100%' }}> {virtualizer.getVirtualItems().map((virtualRow) => ( <div key={virtualRow.index} // ANTI-PATTERN: Positioning via 'top' triggers layout recalculations // ANTI-PATTERN: Missing data-index on dynamic measurement element causes measurement failure ref={virtualizer.measureElement} style={{ position: 'absolute', top: `${virtualRow.start}px`, left: 0, width: '100%', }} > {items[virtualRow.index].content} </div> ))} </div> </div> ); }; ``` #### Production Standard (Correct) > **Standard**: Adheres to performance invariants: 'getItemKey' provides stable identity, 'data-index' is explicitly bound to ensure robust measurement cache mapping, position offsets are calculated via 'transform: translateY' for GPU compositing, 'contain: strict' isolates style and layout computations, and overscan is capped at a conservative 5 items. ```typescript import React, { useRef, useCallback } from 'react'; import { useVirtualizer } from '@tanstack/react-virtual'; interface RowData { id: string; content: string; } export const ProductionVirtualList: React.FC<{ items: RowData[] }> = ({ items }) => { 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, }); return ( <div ref={parentRef} style={{ height: '600px', overflowY: 'auto', contain: 'strict', willChange: 'transform', }} > <div style={{ height: `${virtualizer.getTotalSize()}px`, width: '100%', position: 'relative', }} > {virtualizer.getVirtualItems().map((virtualRow) => { const item = items[virtualRow.index]; return ( <div key={virtualRow.key} data-index={virtualRow.index} ref={virtualizer.measureElement} style={{ position: 'absolute', top: 0, left: 0, width: '100%', transform: `translateY(${virtualRow.start}px)`, }} > {item.content} </div> ); })} </div> </div> ); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Virtual 3.0 Dynamic Windowing and Containment Standard

TanStack Virtual 3.0 Dynamic Windowing and Containment Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict virtual DOM containment, hardware-accelerated transform positioning, and deterministic measurement caching for TanStack Virtual 3.0. Prevents layout thrashing, DOM node saturation, and measurement cache eviction in high-frequency, dynamic-height tabular datasets. 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: Dynamic element measurement without data-index anchors, unmemoized getItemKey, and missing CSS layout containment causing catastrophic reflow loops. 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	Dynamic element measurement without data-index anchors, unmemoized getItemKey, and missing CSS layout containment causing catastrophic reflow loops.	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:

Components measuring dynamic row heights MUST attach 'ref={virtualizer.measureElement}' directly to the rendered node and specify 'data-index={virtualRow.index}' on that exact element.

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.