TanStack Virtual 3.0 Dynamic Measurement and Layout Containment Standard

--- description: TanStack Virtual 3.0 Dynamic Measurement and Layout Containment Standard - Enforces strict DOM node containment, GPU-accelerated absolute transforms, and non-thrashing dynamic element measurement for @tanstack/react-virtual 3.0. Prevents catastrophic layout recalculations and main-thread freezing in high-density tables and lists with variable-height cells. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-virtual-dynamic-measurement-containment" --- # TanStack Virtual 3.0 Dynamic Measurement and Layout Containment Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Dynamic Element Re-rendering with Uncontained Offsets and Inline Height Recalculation Thrashing ## System Constraints You are a Principal Engineer enforcing TanStack Virtual 3.0 Windowing Performance. Mandate invariants around dynamic item measurement, layout containment, transform-based positioning, and controlled overscan limits. ## Strict Guidelines - Engineers MUST ALWAYS attach the 'data-index' attribute alongside 'ref={virtualizer.measureElement}' when dynamically measuring variable-size items. - Engineers MUST NOT position virtualized items using 'top' or 'left' style offsets; positioning MUST use GPU-accelerated 'transform: translateY(...)' or 'translate3d'. - Components NEVER specify an unbounded 'overscan' value; overscan MUST remain bounded between 3 and 10 items to prevent DOM node saturation. - The outer virtualizer parent MUST apply strict containment ('contain: strict' or 'contain: paint layout') to isolate layout reflows from the root document. - Engineers MUST ALWAYS memoize or stabilize the 'estimateSize' function reference passed to 'useVirtualizer' to prevent entire cache invalidation cycles. - Components MUST NOT instantiate layout-reading hooks (e.g., 'getBoundingClientRect' or 'offsetHeight') inside virtual row render paths; defer entirely to 'virtualizer.measureElement'. ## Bad vs Good Implementations ### Dynamic Height Row Virtualization with Containment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using 'top' instead of CSS transforms triggers full document reflow on every scroll tick. Unbounded overscan (100) saturates the DOM. Calling 'measureElement' imperatively inside an inline callback ref without 'data-index' breaks dynamic size caching and causes infinite measure loops in TanStack Virtual 3.0. ```typescript import React, { useRef } from 'react'; import { useVirtualizer } from '@tanstack/react-virtual'; interface RowData { id: string; content: string; } export const BadVirtualTable = ({ rows }: { rows: RowData[] }) => { const parentRef = useRef<HTMLDivElement>(null); // BAD: Dynamic unmemoized estimateSize, unbounded overscan, missing containment const virtualizer = useVirtualizer({ count: rows.length, getScrollElement: () => parentRef.current, estimateSize: () => 50, overscan: 100, }); return ( <div ref={parentRef} style={{ height: '600px', overflowY: 'auto' }}> <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}> {virtualizer.getVirtualItems().map((virtualRow) => ( // BAD: top offset causes reflow; ref attached without data-index breaks dynamic measurement <div key={virtualRow.key} ref={(el) => { if (el) virtualizer.measureElement(el); }} style={{ position: 'absolute', top: `${virtualRow.start}px`, left: 0, width: '100%' }} > {rows[virtualRow.index].content} </div> ))} </div> </div> ); }; ``` #### Production Standard (Correct) > **Standard**: Adheres to TanStack Virtual 3.0 invariants: 'contain: strict' eliminates parent tree reflows, 'transform: translateY' delegates offset positioning to the GPU compositor thread, 'overscan: 5' bounds DOM node saturation, and passing 'ref={virtualizer.measureElement}' with 'data-index' enables reliable ResizeObserver measurement without thrash. ```typescript import React, { useRef, useCallback } from 'react'; import { useVirtualizer } from '@tanstack/react-virtual'; interface RowData { id: string; content: string; } export const GoodVirtualTable = ({ rows }: { rows: RowData[] }) => { const parentRef = useRef<HTMLDivElement>(null); // GOOD: Stable estimate callback, bounded overscan const estimateSize = useCallback(() => 48, []); const virtualizer = useVirtualizer({ count: rows.length, getScrollElement: () => parentRef.current, estimateSize, overscan: 5, }); return ( <div ref={parentRef} style={{ height: '600px', overflowY: 'auto', contain: 'strict', // GOOD: Layout and paint containment isolates scroll thrash }} > <div style={{ height: `${virtualizer.getTotalSize()}px`, width: '100%', position: 'relative', }} > {virtualizer.getVirtualItems().map((virtualRow) => ( <div key={virtualRow.key} data-index={virtualRow.index} // GOOD: Required by TanStack Virtual 3.0 measureElement ref={virtualizer.measureElement} // GOOD: Direct assignment of stable measureElement ref style={{ position: 'absolute', top: 0, left: 0, width: '100%', transform: `translateY(${virtualRow.start}px)`, // GOOD: GPU-accelerated compositor positioning }} > {rows[virtualRow.index].content} </div> ))} </div> </div> ); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Virtual 3.0 Dynamic Measurement and Layout Containment Standard

TanStack Virtual 3.0 Dynamic Measurement and Layout Containment Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict DOM node containment, GPU-accelerated absolute transforms, and non-thrashing dynamic element measurement for @tanstack/react-virtual 3.0. Prevents catastrophic layout recalculations and main-thread freezing in high-density tables and lists with variable-height cells. 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 Re-rendering with Uncontained Offsets and Inline Height Recalculation Thrashing 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 Re-rendering with Uncontained Offsets and Inline Height Recalculation Thrashing	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' attribute alongside 'ref={virtualizer.measureElement}' when dynamically measuring variable-size items.

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.