em-jones/tanstack-virtual

Overview

TanStack Virtual provides virtualization logic for rendering only visible items in large lists, grids, and tables. It calculates which items are in the viewport and positions them with absolute positioning, keeping DOM node count minimal regardless of dataset size.

Core: @tanstack/virtual-core (framework-agnostic)

Installation

# React
npm install @tanstack/react-virtual

# Solid
npm install @tanstack/solid-virtual

Framework Adapters

| Framework | Package | Hook/Function | |-----------|---------|----------------| | React | @tanstack/react-virtual | useVirtualizer, useWindowVirtualizer | | Solid | @tanstack/solid-virtual | createVirtualizer, createWindowVirtualizer | | Vue | @tanstack/vue-virtual | useVirtualizer | | Svelte | @tanstack/svelte-virtual | createVirtualizer |

Core Pattern

React

import { useVirtualizer } from '@tanstack/react-virtual'

function VirtualList() {
  const parentRef = useRef<HTMLDivElement>(null)

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

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

SolidJS

import { createVirtualizer } from '@tanstack/solid-virtual'
import { For } from 'solid-js'

function VirtualList() {
  let parentRef: HTMLDivElement | undefined

  const virtualizer = createVirtualizer({
    get count() { return 10000 },
    getScrollElement: () => parentRef ?? null,
    estimateSize: () => 35,
    overscan: 5,
  })

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

Key SolidJS differences:

• Use createVirtualizer instead of useVirtualizer
• Use <For> instead of .map()
• Use getter functions for reactive options (e.g., get count() { return items.length })
• Refs are assigned via callback: ref={parentRef} or let parentRef: HTMLDivElement | undefined

Virtualizer Options

Required

| Option | Type | Description | |--------|------|-------------| | count | number | Total number of items | | getScrollElement | () => Element \| null | Returns scroll container | | estimateSize | (index) => number | Estimated item size (overestimate recommended) |

Optional

| Option | Type | Default | Description | |--------|------|---------|-------------| | overscan | number | 1 | Extra items rendered beyond viewport | | horizontal | boolean | false | Horizontal virtualization | | gap | number | 0 | Gap between items (px) | | lanes | number | 1 | Number of lanes (masonry/grid) | | paddingStart | number | 0 | Padding before first item | | paddingEnd | number | 0 | Padding after last item | | scrollPaddingStart | number | 0 | Offset for scrollTo positioning | | scrollPaddingEnd | number | 0 | Offset for scrollTo positioning | | initialOffset | number | 0 | Starting scroll position | | initialRect | Rect | - | Initial dimensions (SSR) | | enabled | boolean | true | Enable/disable | | getItemKey | (index) => Key | (i) => i | Stable key for items | | rangeExtractor | (range) => number[] | default | Custom visible indices | | scrollToFn | (offset, options, instance) => void | default | Custom scroll behavior | | measureElement | (el, entry, instance) => number | default | Custom measurement | | onChange | (instance, sync) => void | - | State change callback | | isScrollingResetDelay | number | 150 | Delay before scroll complete |

Virtualizer API

// Get visible items
virtualizer.getVirtualItems(): VirtualItem[]

// Get total scrollable size
virtualizer.getTotalSize(): number

// Scroll to specific index
virtualizer.scrollToIndex(index, { align: 'start' | 'center' | 'end' | 'auto', behavior: 'auto' | 'smooth' })

// Scroll to offset
virtualizer.scrollToOffset(offset, options)

// Force recalculation
virtualizer.measure()

VirtualItem Properties

interface VirtualItem {
  key: Key           // Unique key
  index: number      // Index in source data
  start: number      // Pixel offset (use for transform)
  end: number        // End pixel offset
  size: number       // Item dimension
  lane: number       // Lane index (multi-column)
}

Dynamic/Variable Heights

Use measureElement ref for items with unknown heights:

React

const virtualizer = useVirtualizer({
  count: items.length,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 50,
})

{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)`,
    }}
  >
    {items[virtualItem.index].content}
  </div>
))}

SolidJS

const virtualizer = createVirtualizer({
  get count() { return items.length },
  getScrollElement: () => parentRef ?? null,
  estimateSize: () => 50,
})

<For each={virtualizer.getVirtualItems()}>
  {(virtualItem) => (
    <div
      data-index={virtualItem.index}
      ref={virtualizer.measureElement}
      style={{
        position: 'absolute',
        top: 0,
        left: 0,
        width: '100%',
        transform: `translateY(${virtualItem.start}px)`,
      }}
    >
      {items[virtualItem.index].content}
    </div>
  )}
</For>

Horizontal Virtualization

React

const virtualizer = useVirtualizer({
  count: columns.length,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 100,
  horizontal: true,
})

<div style={{ width: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
  {virtualizer.getVirtualItems().map((item) => (
    <div style={{
      position: 'absolute',
      height: '100%',
      width: `${item.size}px`,
      transform: `translateX(${item.start}px)`,
    }}>
      Column {item.index}
    </div>
  ))}
</div>

SolidJS

const virtualizer = createVirtualizer({
  get count() { return columns.length },
  getScrollElement: () => parentRef ?? null,
  estimateSize: () => 100,
  horizontal: true,
})

<div style={{ width: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
  <For each={virtualizer.getVirtualItems()}>
    {(item) => (
      <div style={{
        position: 'absolute',
        height: '100%',
        width: `${item.size}px`,
        transform: `translateX(${item.start}px)`,
      }}>
        Column {item.index}
      </div>
    )}
  </For>
</div>

Grid Virtualization (Two Virtualizers)

React

function VirtualGrid() {
  const parentRef = useRef<HTMLDivElement>(null)

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

  const columnVirtualizer = useVirtualizer({
    count: 10000,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 100,
    horizontal: true,
    overscan: 5,
  })

  return (
    <div ref={parentRef} style={{ height: '500px', width: '500px', overflow: 'auto' }}>
      <div style={{
        height: `${rowVirtualizer.getTotalSize()}px`,
        width: `${columnVirtualizer.getTotalSize()}px`,
        position: 'relative',
      }}>
        {rowVirtualizer.getVirtualItems().map((virtualRow) => (
          <Fragment key={virtualRow.key}>
            {columnVirtualizer.getVirtualItems().map((virtualColumn) => (
              <div
                key={virtualColumn.key}
                style={{
                  position: 'absolute',
                  width: `${virtualColumn.size}px`,
                  height: `${virtualRow.size}px`,
                  transform: `translateX(${virtualColumn.start}px) translateY(${virtualRow.start}px)`,
                }}
              >
                Cell {virtualRow.index},{virtualColumn.index}
              </div>
            ))}
          </Fragment>
        ))}
      </div>
    </div>
  )
}

SolidJS

function VirtualGrid() {
  let parentRef: HTMLDivElement | undefined

  const rowVirtualizer = createVirtualizer({
    get count() { return 10000 },
    getScrollElement: () => parentRef ?? null,
    estimateSize: () => 35,
    overscan: 5,
  })

  const columnVirtualizer = createVirtualizer({
    get count() { return 10000 },
    getScrollElement: () => parentRef ?? null,
    estimateSize: () => 100,
    horizontal: true,
    overscan: 5,
  })

  return (
    <div ref={parentRef} style={{ height: '500px', width: '500px', overflow: 'auto' }}>
      <div style={{
        height: `${rowVirtualizer.getTotalSize()}px`,
        width: `${columnVirtualizer.getTotalSize()}px`,
        position: 'relative',
      }}>
        <For each={rowVirtualizer.getVirtualItems()}>
          {(virtualRow) => (
            <For each={columnVirtualizer.getVirtualItems()}>
              {(virtualColumn) => (
                <div
                  style={{
                    position: 'absolute',
                    width: `${virtualColumn.size}px`,
                    height: `${virtualRow.size}px`,
                    transform: `translateX(${virtualColumn.start}px) translateY(${virtualRow.start}px)`,
                  }}
                >
                  Cell {virtualRow.index},{virtualColumn.index}
                </div>
              )}
            </For>
          )}
        </For>
      </div>
    </div>
  )
}

Window Scrolling

React

import { useWindowVirtualizer } from '@tanstack/react-virtual'

function WindowList() {
  const listRef = useRef<HTMLDivElement>(null)

  const virtualizer = useWindowVirtualizer({
    count: 10000,
    estimateSize: () => 45,
    overscan: 5,
    scrollMargin: listRef.current?.offsetTop ?? 0,
  })

  return (
    <div ref={listRef}>
      <div style={{
        height: `${virtualizer.getTotalSize()}px`,
        position: 'relative',
      }}>
        {virtualizer.getVirtualItems().map((item) => (
          <div
            key={item.key}
            style={{
              position: 'absolute',
              height: `${item.size}px`,
              transform: `translateY(${item.start - virtualizer.options.scrollMargin}px)`,
            }}
          >
            Row {item.index}
          </div>
        ))}
      </div>
    </div>
  )
}

SolidJS

import { createWindowVirtualizer } from '@tanstack/solid-virtual'
import { For } from 'solid-js'

function WindowList() {
  let listRef: HTMLDivElement | undefined

  const virtualizer = createWindowVirtualizer({
    get count() { return 10000 },
    estimateSize: () => 45,
    overscan: 5,
    get scrollMargin() { return listRef?.offsetTop ?? 0 },
  })

  return (
    <div ref={listRef}>
      <div style={{
        height: `${virtualizer.getTotalSize()}px`,
        position: 'relative',
      }}>
        <For each={virtualizer.getVirtualItems()}>
          {(item) => (
            <div
              style={{
                position: 'absolute',
                height: `${item.size}px`,
                transform: `translateY(${item.start - virtualizer.options.scrollMargin}px)`,
              }}
            >
              Row {item.index}
            </div>
          )}
        </For>
      </div>
    </div>
  )
}

Infinite Scrolling

React

import { useVirtualizer } from '@tanstack/react-virtual'
import { useInfiniteQuery } from '@tanstack/react-query'

function InfiniteList() {
  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
    queryKey: ['items'],
    queryFn: ({ pageParam = 0 }) => fetchItems(pageParam),
    getNextPageParam: (lastPage) => lastPage.nextCursor,
  })

  const allItems = data?.pages.flatMap((page) => page.items) ?? []

  const virtualizer = useVirtualizer({
    count: hasNextPage ? allItems.length + 1 : allItems.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
    overscan: 5,
  })

  useEffect(() => {
    const items = virtualizer.getVirtualItems()
    const lastItem = items[items.length - 1]
    if (lastItem && lastItem.index >= allItems.length - 1 && hasNextPage && !isFetchingNextPage) {
      fetchNextPage()
    }
  }, [virtualizer.getVirtualItems(), hasNextPage, isFetchingNextPage, allItems.length])
}

SolidJS

import { createVirtualizer } from '@tanstack/solid-virtual'
import { createResource, createEffect, For } from 'solid-js'

async function fetchItems(cursor: number) {
  const res = await fetch(`/api/items?cursor=${cursor}`)
  return res.json()
}

function InfiniteList() {
  let parentRef: HTMLDivElement | undefined

  const [items, { refetch }] = createResource(() => fetchItems(0))

  const virtualizer = createVirtualizer({
    get count() { return (items()?.length ?? 0) + (hasNextPage() ? 1 : 0) },
    getScrollElement: () => parentRef ?? null,
    estimateSize: () => 50,
    overscan: 5,
  })

  createEffect(() => {
    const virtualItems = virtualizer.getVirtualItems()
    const lastItem = virtualItems[virtualItems.length - 1]
    if (lastItem && lastItem.index >= (items()?.length ?? 0) - 1 && hasNextPage() && !isFetchingNextPage()) {
      fetchNextPage()
    }
  })
}

Sticky Items

React

import { defaultRangeExtractor, Range } from '@tanstack/react-virtual'

const stickyIndexes = [0, 10, 20, 30]

const virtualizer = useVirtualizer({
  count: 1000,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 50,
  rangeExtractor: useCallback((range: Range) => {
    const next = new Set([...stickyIndexes, ...defaultRangeExtractor(range)])
    return [...next].sort((a, b) => a - b)
  }, [stickyIndexes]),
})

SolidJS

import { defaultRangeExtractor } from '@tanstack/virtual-core'

const stickyIndexes = [0, 10, 20, 30]

const virtualizer = createVirtualizer({
  get count() { return 1000 },
  getScrollElement: () => parentRef ?? null,
  estimateSize: () => 50,
  rangeExtractor: (range) => {
    const next = new Set([...stickyIndexes, ...defaultRangeExtractor(range)])
    return [...next].sort((a, b) => a - b)
  },
})

Smooth Scrolling

const virtualizer = useVirtualizer({
  scrollToFn: (offset, { behavior }, instance) => {
    if (behavior === 'smooth') {
      // Custom easing animation
      instance.scrollElement?.scrollTo({ top: offset, behavior: 'smooth' })
    } else {
      instance.scrollElement?.scrollTo({ top: offset })
    }
  },
})

// Usage
virtualizer.scrollToIndex(500, { align: 'center', behavior: 'smooth' })

Best Practices

1. Overestimate estimateSize - prevents scroll jumps (items shrinking causes issues)
2. Increase overscan (3-5) to reduce blank flashing during fast scrolling
3. Use transform: translateY() over top for GPU-composited positioning
4. Add data-index attribute when using measureElement for dynamic sizing
5. Don't set fixed height on dynamically measured items
6. Use getItemKey for stable keys when items can reorder
7. Use gap option instead of margins (margins interfere with measurement)
8. Use paddingStart/End instead of CSS padding on the container
9. Use enabled: false to pause when the list is hidden
10. Memoize callbacks (estimateSize, getItemKey, rangeExtractor)
11. Use will-change: transform CSS on items for GPU acceleration

SolidJS-Specific Notes

• Use getter functions for reactive options: get count() { return items.length }
• Import from @tanstack/virtual-core for utilities like defaultRangeExtractor
• Solid's <For> component handles keying automatically via the item
• For dynamic counts, make the count option a getter for reactivity

Common Pitfalls

• Setting fixed height on dynamically measured items
• Using CSS margins instead of the gap option
• Forgetting data-index with measureElement
• Not providing position: relative on the inner container
• Underestimating estimateSize (causes scroll jumps)
• Setting overscan too low for fast scrolling (blank items)
• Forgetting to subtract scrollMargin from translateY in window scrolling
• Not memoizing the estimateSize function (causes re-renders)