ReactのTanStack Virtualで、高さの違う行を仮想スクロールする方法
チャットのメッセージやコメントの一覧のように、行ごとに高さが違う長い一覧も、TanStack Virtual の useVirtualizer を使えば仮想スクロールできます。行の高さを前もって知らなくても、描いた行の高さをあとから測らせれば、行どうしが重ならずに並びます。そのために行の要素に付けるのは、ref={virtualizer.measureElement} と data-index の2つです。
検証環境で試したところ、本文の長さが違う1万件の一覧でも、DOM にある行は4〜8行でした。行の高さは 41px から 185px までばらばらですが、となりの行と重なる行も、すき間のある行もありませんでした。
検証環境は Ubuntu 24.04、Node.js 22.23.4 です。使ったのは react / react-dom 19.3.1、@tanstack/react-virtual 3.14.26(中で使われる @tanstack/virtual-core は 3.19.11)、@types/react 19.3.0、typescript 7.0.2、esbuild 0.28.2 です。.tsx を tsc で型チェックしてから esbuild で本番用にビルドし、ヘッドレスの Chromium 153(Chrome for Testing。Playwright 1.63.0 で操作)で動かしました。StrictMode では包んでいません。ウィンドウ全体でスクロールする useWindowVirtualizer、横向きの一覧、scrollToIndex での移動、行の中身があとから変わる場合、実機のスマホは試していません。
行を描いたあとに、measureElement で高さを測らせる
TanStack Virtual の React 版は npm install @tanstack/react-virtual で入れます(公式ドキュメントのインストールの説明)。
次のコードは、高さの違う行を並べる一覧です。行の本文は「メッセージの本文がここに入ります。」を1〜8回くり返した文で、一覧の高さは 400px、幅は 360px にしました。
import { useRef } from 'react';
import { useVirtualizer } from '@tanstack/react-virtual';
import type { Item } from './items';
// 高さの違う行を、描いたあとに測って並べる一覧
export function DynamicList({ items }: { items: Item[] }) {
const parentRef = useRef<HTMLDivElement>(null);
const virtualizer = useVirtualizer({
count: items.length,
getScrollElement: () => parentRef.current,
estimateSize: () => 80,
});
return (
<div ref={parentRef} className="scroller" style={{ height: 400, overflowY: 'auto' }}>
<div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}>
{virtualizer.getVirtualItems().map((row) => (
<div
key={row.key}
data-index={row.index}
ref={virtualizer.measureElement}
className="row"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
transform: `translateY(${row.start}px)`,
}}
>
<strong>#{items[row.index].id}</strong> {items[row.index].text}
</div>
))}
</div>
</div>
);
}
Item は { id: number; text: string } の型です。.row には CSS で padding: 8px 12px と下の罫線を付けていて、行の高さは決めていません。
useVirtualizer に渡しているのは次の3つです。どれも Virtualizer の API リファレンスで、必ず渡すオプションになっています。
| オプション | 渡すもの |
|---|---|
count |
一覧の件数 |
getScrollElement |
スクロールする要素を返す関数 |
estimateSize |
行の高さの見積もり(px)を返す関数 |
getVirtualItems() は、いま描くべき行の一覧を返します。VirtualItem の API リファレンスにあるとおり、返される1つ1つの要素には、行の番号 index、行を区別する key(初期値は行の番号)、全体の中の上端の位置 start が入っています。この start を translateY に渡して、行を置きます。内側の div の高さには getTotalSize() を渡し、スクロールできる長さを作ります。
高さの違う行で欠かせないのは、行の要素に付けた ref={virtualizer.measureElement} と data-index={row.index} です。API リファレンスの、インスタンスの measureElement の説明には、行を描いたときに React の ref コールバックなどでこの関数を呼び、data-index も付けるよう書かれています。測った高さは、後ろの行の start の計算に使われます。
1万件で、行の高さと位置を DOM から調べた
この一覧を1万件で描き、DOM にある行の高さと上端の位置を Playwright で読み取りました。上端は、一覧の中身の先頭から数えた位置です。
スクロール前: scrollTop=0 全体の高さ=800366 .rowの数=4 最初=#1 最後=#4
行の高さ(px)=113,113,185,137
行の上端(px)=0,113,226,411
前の行と重なる行=0(最大 0px) すき間がある行=0
scrollTop=200000 に設定したあと: scrollTop=200066 全体の高さ=800750 .rowの数=7 最初=#2495 最後=#2501
行の高さ(px)=113,113,113,41,185,113,185
行の上端(px)=199886,199999,200112,200225,200266,200451,200564
前の行と重なる行=0(最大 0px) すき間がある行=0
どの行も、上端が前の行の上端と高さを足した位置にあり、重なりもすき間もありません。たとえばスクロール前の1行目は高さ 113px で、2行目は 113px の位置から始まっています。
DOM にある行は、スクロール前で4行、中ほどで7行でした。高さ 400px の枠に見えている行に、その前後の1行ずつを足した数です(スクロール前は前の行がないので、後ろの1行だけです)。API リファレンスの overscan の説明にあるとおり、見えている範囲の外に余分に描く行の数は、初期値が 1 です。npm で配布されている @tanstack/virtual-core 3.19.11 のコードでも、overscan の初期値は 1 でした。
ホイールでスクロールしたときの様子を、GIF にしました。

ホイールは1回につき 100px ずつ、36回動かしています。カーソルと下の枠は、撮影用のスクリプトが書き足したものです。枠には、各コマで DOM を調べた結果を出していて、一部だけ見えている行も「見えている行」に数えています。値が変わったコマだけ、その値をピンクにしています。撮影のときに各コマで調べても、となりの行と重なる行はなく、DOM にある行は4行から8行のあいだでした。
measureElement と data-index の付け忘れで、行が重なる
ref に measureElement を渡していない
行の要素から ref={virtualizer.measureElement} と data-index を外すと、行は見積もりの 80px おきに並びました。スクロール前に描かれた6行は、どれも 80px より高いので、次の行が上に重なります。
スクロール前: scrollTop=0 全体の高さ=800000 .rowの数=6 最初=#1 最後=#6
行の高さ(px)=113,113,185,137,161,137
行の上端(px)=0,80,160,240,320,400
前の行と重なる行=5(最大 105px) すき間がある行=0
全体の高さは、1万件 × 80px の 800,000px のままでした。画面では、行の本文が途中で次の行に隠れます。

measureElement を渡したのに、data-index がない
ref={virtualizer.measureElement} は付けて、data-index だけを付け忘れた場合も試しました。行の位置は、付けない場合と同じ 80px おきで、同じように重なりました。ブラウザのコンソールには、スクロールの前とあとで合わせて13回、次の警告が出ました。
Missing attribute name 'data-index={index}' on measured element.
@tanstack/virtual-core 3.19.11 の配布コードを見ると、measureElement に渡された要素から data-index 属性を読み、行の番号を知る作りになっています。属性がないと、この警告を出して -1 を返します。-1 は行の番号の範囲の外なので、measureElement はその要素の高さを測らずに戻ります。属性の名前は、indexAttribute オプションの初期値の data-index です。
行が重なったら、行の要素に ref={virtualizer.measureElement} と data-index={row.index} の両方が付いているかを確かめてください。片方だけでは、高さは測られません。
全体の高さは、まだ測っていない行を見積もりで計算する
スクロール前の全体の高さ(getTotalSize())は 800,366px でした。同じ1万件をすべて描いた一覧では、全体の高さは 1,123,304px です。
すべて描いた一覧: .rowの数=10000 全体の高さ=1123304 行の高さ=41〜185px
getTotalSize() が小さいのは、まだ描いていない行を estimateSize の 80px として計算しているからです。配布コードでも、測った高さがない行は estimateSize の値を使っていました。API リファレンスの getTotalSize の説明にあるように、この値は行を測るたびに少しずつ変わります。先ほどの GIF でも、スクロールするにつれて、全体の高さが少しずつ変わっていました。
見積もりのままでも、一覧の最後まではたどり着けます。scrollTop に一覧のいちばん下の値を入れると、測った行のぶん全体の高さが変わるので、もう一度いちばん下へ動かしました。3回目で全体の高さが変わらなくなり、最後の #10000 の行が DOM にありました。
一番下へのスクロール: 3回目で全体の高さが変わらなくなった
一番下: scrollTop=800278 全体の高さ=800678 .rowの数=8 最初=#9993 最後=#10000
行の高さ(px)=113,65,113,41,89,41,41,65
行の上端(px)=800110,800223,800288,800401,800442,800531,800572,800613
前の行と重なる行=0(最大 0px) すき間がある行=0
API リファレンスの estimateSize の説明では、高さを測る場合は、行のいちばん大きい高さに近い値を estimateSize で返すよう勧めています。そのほうが、最初に計算する位置が正確になるとあります。この検証の 80px は、実際の行(41〜185px)の中では小さめの値です。





