TanStack Virtual 3.0 Invariants: Dynamic Measurement, Data-Index Binding, and DOM Containment

--- description: TanStack Virtual 3.0 Invariants: Dynamic Measurement, Data-Index Binding, and DOM Containment - Enforces strict DOM node containment, dynamic height measurement invariants, and GPU-composited positioning for TanStack Virtual 3.0. Prevents layout thrashing, infinite measurement cycles, and DOM node saturation in massive multi-thousand-row tables. Mandates deterministic data-index attribution and hardware-accelerated transform offsets. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-virtual-dynamic-measurement-saturation-prevention" --- # TanStack Virtual 3.0 Invariants: Dynamic Measurement, Data-Index Binding, and DOM Containment > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Missing data-index Attribute on Dynamic Measurement Nodes Inducing Measurement Thrashing and DOM Node Saturation ## System Constraints You are a Principal Frontend Architect enforcing TanStack Virtual 3.0 performance invariants. You must prevent layout thrashing, dynamic element measurement desynchronization, and DOM node saturation. Ensure all virtualizers strictly register data-index attributes on measured nodes, use transform3d/translateY for positioning, clamp overscan budgets, and apply CSS containment to parent and item wrappers. ## Strict Guidelines - Engineers MUST ALWAYS attach the `data-index={virtualRow.index}` attribute to the exact DOM element passed to `ref={rowVirtualizer.measureElement}` when dynamic measurement is active. - Engineers MUST NOT position virtualized items using CSS `top` or `margin-top`; they MUST use GPU-composited `transform: translateY(${virtualRow.start}px)` to avoid re-triggering browser layout and paint phases. - Engineers MUST constrain the `overscan` option to between 3 and 10 items; values exceeding 15 require documented performance profiling to avoid DOM node saturation. - The scrollable container MUST define an inner relative container sized explicitly with `height: ${rowVirtualizer.getTotalSize()}px` to maintain accurate native scrollbar track metrics. - Components rendering dynamic virtual rows MUST define CSS layout containment (`contain: strict` or `contain: content`) on individual virtual row elements to isolate dynamic dimension recalculations. - Engineers MUST pass a deterministic, persistent `getItemKey` callback into `useVirtualizer` to avoid measurement cache invalidation and DOM recycling bugs during list sorting or filtering. ## Bad vs Good Implementations ### Dynamic Element Measurement & Containment in Massive Lists #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: 1. Omitting `data-index` while using `measureElement` causes TanStack Virtual to fail to map mutations back to the cache, triggering layout thrashing and measurement desync. 2. `top: ${virtualRow.start}px` triggers continuous layout recalculations during scrolling instead of composited transforms. 3. `overscan: 50` saturates the DOM with excessive nodes. 4. Missing inner container with `getTotalSize()` breaks scrollbar physics. 5. Keying by index breaks dynamic measurement on sorting/reordering. ```typescript import React, { useRef } from 'react'; import { useVirtualizer } from '@tanstack/react-virtual'; interface Item { id: string; content: string; } export const BadVirtualTable = ({ items }: { items: Item[] }) => { const parentRef = useRef<HTMLDivElement>(null); const rowVirtualizer = useVirtualizer({ count: items.length, getScrollElement: () => parentRef.current, estimateSize: () => 50, overscan: 50, // Massive overscan causing DOM saturation }); return ( <div ref={parentRef} style={{ height: '600px', overflowY: 'auto' }}> {/* Missing height: rowVirtualizer.getTotalSize() container */} {rowVirtualizer.getVirtualItems().map((virtualRow) => ( <div key={virtualRow.index} // Non-deterministic key if items reorder ref={rowVirtualizer.measureElement} // Missing data-index leads to measurement cache desync style={{ position: 'absolute', top: `${virtualRow.start}px`, // Triggers layout thrashing left: 0, width: '100%', }} > {items[virtualRow.index]?.content} </div> ))} </div> ); }; ``` #### Production Standard (Correct) > **Standard**: 1. `data-index={virtualRow.index}` is explicitly attached so `measureElement` maps measurements accurately to the internal cache without ref mismatch. 2. Positioning uses `transform: translateY(...)` combined with `will-change: transform`, keeping scroll handling on the GPU compositor thread. 3. `overscan: 5` prevents DOM node saturation. 4. Inner container with explicit `getTotalSize()` preserves scrollbar metric accuracy. 5. `contain: strict` on the parent and `contain: content` on dynamic rows isolate reflow recalculations. ```typescript import React, { useRef } from 'react'; import { useVirtualizer } from '@tanstack/react-virtual'; interface Item { id: string; content: string; } export const GoodVirtualTable = ({ items }: { items: Item[] }) => { const parentRef = useRef<HTMLDivElement>(null); const rowVirtualizer = useVirtualizer({ count: items.length, getScrollElement: () => parentRef.current, estimateSize: () => 56, getItemKey: (index) => items[index]?.id ?? index, overscan: 5, }); return ( <div ref={parentRef} style={{ height: '600px', overflowY: 'auto', contain: 'strict', }} > <div style={{ height: `${rowVirtualizer.getTotalSize()}px`, width: '100%', position: 'relative', }} > {rowVirtualizer.getVirtualItems().map((virtualRow) => ( <div key={virtualRow.key} data-index={virtualRow.index} ref={rowVirtualizer.measureElement} style={{ position: 'absolute', top: 0, left: 0, width: '100%', transform: `translateY(${virtualRow.start}px)`, contain: 'content', willChange: 'transform', }} > {items[virtualRow.index]?.content} </div> ))} </div> </div> ); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Virtual 3.0 Invariants: Dynamic Measurement, Data-Index Binding, and DOM Containment

TanStack Virtual 3.0 Invariants: Dynamic Measurement, Data-Index Binding, and DOM Containment defines an industrial-grade behavioral standard for frontend engineering. Enforces strict DOM node containment, dynamic height measurement invariants, and GPU-composited positioning for TanStack Virtual 3.0. Prevents layout thrashing, infinite measurement cycles, and DOM node saturation in massive multi-thousand-row tables. Mandates deterministic data-index attribution and hardware-accelerated transform offsets. 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: Missing data-index Attribute on Dynamic Measurement Nodes Inducing Measurement Thrashing and DOM Node Saturation 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	Missing data-index Attribute on Dynamic Measurement Nodes Inducing Measurement Thrashing and DOM Node Saturation	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 attach the `data-index={virtualRow.index}` attribute to the exact DOM element passed to `ref={rowVirtualizer.measureElement}` when dynamic measurement is active.

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.