TanStack Virtual 3.0 Dynamic Windowing & Scroll Margin Containment Invariants

--- description: TanStack Virtual 3.0 Dynamic Windowing & Scroll Margin Containment Invariants - Enforces strict DOM node containment, robust dynamic measurement, and hardware-accelerated transform positioning for TanStack Virtual 3.0. Prevents layout thrashing, scroll-jitter during asynchronous resizing, and DOM saturation when rendering datasets in excess of 100,000 rows. Mandates exact absolute offset styling, ref measurement bindings, and scroll margin synchronization across all high-density tables and lists. 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-guardrails" --- # TanStack Virtual 3.0 Dynamic Windowing & Scroll Margin Containment Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unmeasured variable-height nodes rendered via flow layout top offsets causing sub-pixel jitter and DOM saturation ## System Constraints You are a Principal Engineer enforcing TanStack Virtual 3.0 Windowing Performance. Mandate invariants regarding dynamic element measurement, absolute CSS positioning with GPU-accelerated translateY, accurate estimateSize fallbacks, data-index ref binding, and strict layout containment. ## Strict Guidelines - Components MUST ALWAYS position virtual items using `position: absolute; top: 0; left: 0; transform: translateY(${virtualItem.start}px)` instead of `top: ${virtualItem.start}px` or inline flow layout margins to bypass style recalculation bottlenecks. - Engineers MUST attach `rowVirtualizer.measureElement` as a `ref` attribute directly on the root rendered element of each virtual row when items have dynamic or variable heights. - Engineers MUST NOT rely on default `estimateSize` values without empirical baseline heights, and dynamic rows MUST expose an explicit `data-index={virtualItem.index}` attribute to enable cache lookup in the ResizeObserver pipeline. - The outer scroll container MUST enforce `contain: strict` or `contain: content`, `overflow: auto`, and explicit bounds (height/maxHeight) to isolate layout paint cycles from the global document tree. - When dynamic content (images, async text updates) loads post-mount, components MUST dispatch explicit reflow triggers or guarantee parent container dimension stability to prevent scroll-anchor snapping. - Table header or footer sticky elements inside the virtualized tree MUST utilize `scrollMargin` in virtualizer options rather than unmeasured offsets that displace index calculation bounds. ## Bad vs Good Implementations ### Dynamic Height Row Virtualization with Sub-pixel Measurement Containment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using `top` triggers layout repaints on every scroll frame. Omitting `virtualizer.measureElement` causes dynamic content to clip or overlap when varying from the hardcoded `35px` estimate. Missing `data-index` fails TanStack 3.0's DOM observer lookup. ```typescript import React from 'react'; import { useVirtualizer } from '@tanstack/react-virtual'; export const FlawedVirtualTable = ({ items }: { items: Array<{ id: string; content: string }> }) => { const parentRef = React.useRef<HTMLDivElement>(null); // ANTI-PATTERN: estimateSize mismatch, no measureElement ref, flow layout positioning with top const virtualizer = useVirtualizer({ count: items.length, getScrollElement: () => parentRef.current, estimateSize: () => 35, }); return ( <div ref={parentRef} style={{ height: '600px', overflowY: 'scroll' }}> <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}> {virtualizer.getVirtualItems().map((virtualItem) => ( <div key={virtualItem.key} style={{ position: 'absolute', top: `${virtualItem.start}px`, left: 0, width: '100%', }} > {/* Missing dynamic ref; async content breaks layout without resize listener */} <div style={{ padding: '8px' }}>{items[virtualItem.index].content}</div> </div> ))} </div> </div> ); }; ``` #### Production Standard (Correct) > **Standard**: Adheres to GPU acceleration via `translateY`, binds `data-index` and `measureElement` for ResizeObserver measurements, and isolates rendering boundaries using CSS `contain: strict`. ```typescript import React from 'react'; import { useVirtualizer } from '@tanstack/react-virtual'; export const OptimizedVirtualTable = ({ items }: { items: Array<{ id: string; content: string }> }) => { const parentRef = React.useRef<HTMLDivElement>(null); const virtualizer = useVirtualizer({ count: items.length, getScrollElement: () => parentRef.current, estimateSize: () => 56, overscan: 5, }); return ( <div ref={parentRef} style={{ height: '600px', overflowY: 'auto', contain: 'strict', willChange: 'scroll-position', }} > <div style={{ height: `${virtualizer.getTotalSize()}px`, width: '100%', position: 'relative', }} > {virtualizer.getVirtualItems().map((virtualItem) => ( <div key={virtualItem.key} data-index={virtualItem.index} ref={virtualizer.measureElement} style={{ position: 'absolute', top: 0, left: 0, width: '100%', transform: `translateY(${virtualItem.start}px)`, willChange: 'transform', }} > <div style={{ padding: '12px', borderBottom: '1px solid #e2e8f0' }}> {items[virtualItem.index].content} </div> </div> ))} </div> </div> ); }; ```

Architectural Specification & Invariant Rationale

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

TanStack Virtual 3.0 Dynamic Windowing & Scroll Margin Containment Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict DOM node containment, robust dynamic measurement, and hardware-accelerated transform positioning for TanStack Virtual 3.0. Prevents layout thrashing, scroll-jitter during asynchronous resizing, and DOM saturation when rendering datasets in excess of 100,000 rows. Mandates exact absolute offset styling, ref measurement bindings, and scroll margin synchronization across all high-density tables and lists. 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: Unmeasured variable-height nodes rendered via flow layout top offsets causing sub-pixel jitter and DOM 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	Unmeasured variable-height nodes rendered via flow layout top offsets causing sub-pixel jitter and DOM 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:

Components MUST ALWAYS position virtual items using `position

Components MUST ALWAYS position virtual items using `position: absolute; top: 0; left: 0; transform: translateY(${virtualItem.start}px)` instead of `top: ${virtualItem.start}px` or inline flow layout margins to bypass style recalculation bottlenecks.

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.