Chapter 1: Introduction

Core Idea

TanStack Virtual is a headless utility for virtualizing long JavaScript or TypeScript lists. It calculates which items should exist and where they belong, while the application owns markup, styles, and accessibility.

Key Concepts

• Headless: No component markup or CSS is supplied; the application keeps full rendering control.
• Virtualizer: The core object that tracks scroll state, item sizes, and the visible range.
• Virtual range: The small set of indexes rendered around the viewport instead of the entire collection.
• Vertical axis: The default orientation, with item size interpreted as height.
• Horizontal axis: Enabled with horizontal: true, with size interpreted as width.
• Grid virtualization: Two virtualizers can independently manage rows and columns.
• Total size: The inner spacer represents the full logical list through getTotalSize().
• Overscan: Extra items rendered outside the viewport for smoother fast scrolling.

Code Examples

const rowVirtualizer = useVirtualizer({
  count: 10000,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 35,
})

<div ref={parentRef} style={{ height: 400, overflow: 'auto' }}>
  <div style={{ height: rowVirtualizer.getTotalSize(), position: 'relative' }}>
    {rowVirtualizer.getVirtualItems().map((virtualItem) => (
      <div
        key={virtualItem.key}
        style={{
          position: 'absolute',
          top: 0,
          left: 0,
          width: '100%',
          height: virtualItem.size,
          transform: `translateY(${virtualItem.start}px)`,
        }}
      >
        Row {virtualItem.index}
      </div>
    ))}
  </div>
</div>

• What it demonstrates: The essential scroll element, spacer, range, and absolute positioning contract.

Key Takeaways

1. Virtualization reduces mounted DOM work without prescribing visual design.
2. The scroll container must have a usable viewport and overflow.
3. The same core model supports lists, horizontal collections, and grids.
4. Rendering is driven by virtual item geometry, not by manually slicing data.

Connects To

• Ch 003: React supplies the primary adapter used by this skill.
• Ch 007: The Virtualizer API defines the options used here.
• Ch 009: Fixed-size examples apply this skeleton to rows, columns, and grids.