docs-i18n 0.8.1 → 0.8.3

package/template/content/virtual/en/guides/dynamic-sizing.md

@@ -0,0 +1,129 @@
+---
+title: Dynamic Sizing
+description: Learn how to handle dynamically sized elements with TanStack Virtual
+---
+
+# Dynamic Sizing
+
+By default, TanStack Virtual assumes all items have the same size. However, many real-world use cases require items with varying heights or widths. The `measureElement` option enables dynamic sizing by measuring actual DOM elements.
+
+## Basic Dynamic Sizing
+
+To enable dynamic sizing, pass the `measureElement` function to your virtualizer and attach the provided ref to each item:
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual'
+
+function DynamicList({ items }: { items: string[] }) {
+  const parentRef = React.useRef<HTMLDivElement>(null)
+
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 50, // estimated height in px
+    measureElement: (element) => {
+      return element.getBoundingClientRect().height
+    },
+  })
+
+  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}
+            ref={virtualizer.measureElement}
+            data-index={virtualItem.index}
+            style={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              width: '100%',
+              transform: `translateY(${virtualItem.start}px)`,
+            }}
+          >
+            {items[virtualItem.index]}
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+```
+
+## Estimated Size
+
+The `estimateSize` function provides an initial size estimate before measurement occurs. A good estimate reduces layout shifts:
+
+```tsx
+const virtualizer = useVirtualizer({
+  count: 10000,
+  getScrollElement: () => parentRef.current,
+  estimateSize: (index) => {
+    // Different estimates based on item type
+    if (items[index].type === 'header') return 80
+    if (items[index].type === 'image') return 200
+    return 50
+  },
+})
+```
+
+> [!NOTE]
+> The `estimateSize` function receives the item index, so you can provide different estimates based on item data. Better estimates lead to smoother scrolling.
+
+## Performance Considerations
+
+Dynamic sizing involves DOM measurement, which can be expensive. Here are some tips:
+
+| Technique | Description |
+|---|---|
+| Good estimates | Provide accurate `estimateSize` values to minimize re-measurements |
+| Overscan | Use `overscan` to render extra items outside the viewport |
+| Stable keys | Provide stable `key` values to avoid unnecessary re-renders |
+| CSS containment | Use `contain: strict` on the scroll container for better paint performance |
+
+```tsx
+const virtualizer = useVirtualizer({
+  count: items.length,
+  getScrollElement: () => parentRef.current,
+  estimateSize: () => 50,
+  overscan: 5, // Render 5 extra items on each side
+})
+```
+
+## Handling Resizes
+
+When item content can change size after initial render (e.g., images loading, accordions expanding), you need to re-measure:
+
+```tsx
+// Re-measure a specific item
+virtualizer.resizeItem(index, newSize)
+
+// Re-measure all items
+virtualizer.measure()
+```
+
+> [!WARNING]
+> Calling `measure()` on every render will cause performance issues. Only call it when you know sizes have actually changed, such as after a window resize or content update.
+
+## Horizontal Dynamic Sizing
+
+Dynamic sizing also works for horizontal lists. Use `horizontal: true` and measure width instead of height:
+
+```tsx
+const virtualizer = useVirtualizer({
+  horizontal: true,
+  count: items.length,
+  getScrollElement: () => parentRef.current,
+  estimateSize: () => 100,
+  measureElement: (element) => {
+    return element.getBoundingClientRect().width
+  },
+})
+```

package/template/content/virtual/en/installation.md

@@ -0,0 +1,57 @@
+---
+title: Installation
+description: How to install TanStack Virtual in your project
+---
+
+# Installation
+
+## React
+
+```bash
+npm install @tanstack/react-virtual
+```
+
+```bash
+pnpm add @tanstack/react-virtual
+```
+
+```bash
+yarn add @tanstack/react-virtual
+```
+
+```bash
+bun add @tanstack/react-virtual
+```
+
+## Vue
+
+```bash
+npm install @tanstack/vue-virtual
+```
+
+## Solid
+
+```bash
+npm install @tanstack/solid-virtual
+```
+
+## Svelte
+
+```bash
+npm install @tanstack/svelte-virtual
+```
+
+## Requirements
+
+- React 18+ / Vue 3+ / Solid 1.6+ / Svelte 4+
+- A scroll container with a fixed height (or width for horizontal lists)
+
+## Bundle Size
+
+TanStack Virtual is extremely lightweight:
+
+| Package | Size (gzipped) |
+|---------|---------------|
+| `@tanstack/virtual-core` | ~2.5 KB |
+| `@tanstack/react-virtual` | ~3.5 KB |
+| `@tanstack/vue-virtual` | ~3.5 KB |

package/template/content/virtual/en/overview.md

@@ -0,0 +1,74 @@
+---
+title: TanStack Virtual Overview
+description: Headless UI for virtualizing large element lists at 60FPS
+---
+
+# TanStack Virtual
+
+TanStack Virtual provides headless utilities for virtualizing long lists of elements. It handles the logic of which items to render based on scroll position, while you retain full control over markup and styles.
+
+## Why Virtualization?
+
+Rendering thousands of DOM nodes at once causes significant performance issues. Virtualization solves this by only rendering the items currently visible in the viewport, plus a small overscan buffer.
+
+## Features
+
+- **Framework Agnostic** — Works with React, Vue, Solid, Svelte, and vanilla JS
+- **Vertical & Horizontal** — Virtualize lists in any direction
+- **Grid Virtualization** — Combine vertical and horizontal virtualizers for grids
+- **Dynamic Row Heights** — Supports variable-size items with measurement
+- **Sticky Items** — Pin items to the top or bottom of the scroll area
+- **Scroll Restoration** — Maintain scroll position across navigation
+- **Tiny Bundle** — Under 5KB gzipped
+
+## Basic Example
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual'
+
+function VirtualList() {
+  const parentRef = React.useRef<HTMLDivElement>(null)
+
+  const virtualizer = useVirtualizer({
+    count: 10000,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 35,
+  })
+
+  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>
+  )
+}
+```
+
+## When to Use TanStack Virtual
+
+- Lists with 100+ items
+- Tables with many rows
+- Chat/message interfaces
+- Infinite scrolling feeds
+- Any UI with dynamic, large datasets

package/template/content/virtual/en/quick-start.md

@@ -0,0 +1,114 @@
+---
+title: Quick Start
+description: Get up and running with TanStack Virtual
+---
+
+# Quick Start
+
+## Basic Vertical List
+
+Create a virtualizer for a simple vertical list:
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual'
+
+function RowVirtualizer() {
+  const parentRef = React.useRef<HTMLDivElement>(null)
+
+  const rowVirtualizer = useVirtualizer({
+    count: 10000,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 35,
+    overscan: 5,
+  })
+
+  return (
+    <div
+      ref={parentRef}
+      style={{ height: '400px', overflow: 'auto' }}
+    >
+      <div
+        style={{
+          height: `${rowVirtualizer.getTotalSize()}px`,
+          width: '100%',
+          position: 'relative',
+        }}
+      >
+        {rowVirtualizer.getVirtualItems().map((virtualRow) => (
+          <div
+            key={virtualRow.index}
+            style={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              width: '100%',
+              height: `${virtualRow.size}px`,
+              transform: `translateY(${virtualRow.start}px)`,
+            }}
+          >
+            Row {virtualRow.index}
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+```
+
+## Dynamic Row Heights
+
+For variable-height items, provide a `measureElement` callback:
+
+```tsx
+const rowVirtualizer = useVirtualizer({
+  count: items.length,
+  getScrollElement: () => parentRef.current,
+  estimateSize: () => 50, // estimated height
+})
+
+// In your rendered items:
+{rowVirtualizer.getVirtualItems().map((virtualRow) => (
+  <div
+    key={virtualRow.index}
+    ref={rowVirtualizer.measureElement}
+    data-index={virtualRow.index}
+  >
+    {items[virtualRow.index].content}
+  </div>
+))}
+```
+
+## Horizontal List
+
+Pass the `horizontal` option to virtualize a horizontal list:
+
+```tsx
+const columnVirtualizer = useVirtualizer({
+  horizontal: true,
+  count: 10000,
+  getScrollElement: () => parentRef.current,
+  estimateSize: () => 100,
+})
+```
+
+## Grid Virtualization
+
+Combine two virtualizers for grid layouts:
+
+```tsx
+const rowVirtualizer = useVirtualizer({
+  count: 10000,
+  getScrollElement: () => parentRef.current,
+  estimateSize: () => 35,
+})
+
+const columnVirtualizer = useVirtualizer({
+  horizontal: true,
+  count: 10000,
+  getScrollElement: () => parentRef.current,
+  estimateSize: () => 100,
+})
+```
+
+> [!NOTE]
+> The `overscan` option controls how many items are rendered outside the visible area. Higher values reduce flicker during fast scrolling but use more memory.

package/template/content/virtual/ja/installation.md

@@ -0,0 +1,57 @@
+---
+title: インストール
+description: プロジェクトに TanStack Virtual をインストールする方法
+---
+
+# インストール
+
+## React
+
+```bash
+npm install @tanstack/react-virtual
+```
+
+```bash
+pnpm add @tanstack/react-virtual
+```
+
+```bash
+yarn add @tanstack/react-virtual
+```
+
+```bash
+bun add @tanstack/react-virtual
+```
+
+## Vue
+
+```bash
+npm install @tanstack/vue-virtual
+```
+
+## Solid
+
+```bash
+npm install @tanstack/solid-virtual
+```
+
+## Svelte
+
+```bash
+npm install @tanstack/svelte-virtual
+```
+
+## 必要要件
+
+- React 18+ / Vue 3+ / Solid 1.6+ / Svelte 4+
+- 固定の高さ（水平リストの場合は幅）を持つスクロールコンテナ
+
+## バンドルサイズ
+
+TanStack Virtual は非常に軽量です：
+
+| パッケージ | サイズ（gzip） |
+|---------|---------------|
+| `@tanstack/virtual-core` | ~2.5 KB |
+| `@tanstack/react-virtual` | ~3.5 KB |
+| `@tanstack/vue-virtual` | ~3.5 KB |

package/template/content/virtual/ja/overview.md

@@ -0,0 +1,74 @@
+---
+title: TanStack Virtual 概要
+description: 大規模な要素リストを 60FPS で仮想化するヘッドレス UI
+---
+
+# TanStack Virtual
+
+TanStack Virtual は、長いリスト要素を仮想化するためのヘッドレスユーティリティを提供します。スクロール位置に基づいてどのアイテムをレンダリングするかのロジックを処理し、マークアップとスタイルの完全な制御はあなたに委ねます。
+
+## なぜ仮想化が必要なのか？
+
+一度に数千の DOM ノードをレンダリングすると、深刻なパフォーマンスの問題が発生します。仮想化は、ビューポートに現在表示されているアイテムと少量のオーバースキャンバッファのみをレンダリングすることで、この問題を解決します。
+
+## 特徴
+
+- **フレームワーク非依存** — React、Vue、Solid、Svelte、バニラ JS で動作
+- **垂直・水平** — 任意の方向でリストを仮想化
+- **グリッド仮想化** — 垂直と水平のバーチャライザーを組み合わせてグリッドを実現
+- **動的な行の高さ** — 可変サイズのアイテムと計測をサポート
+- **固定アイテム** — スクロール領域の上部または下部にアイテムを固定
+- **スクロール復元** — ナビゲーション間でスクロール位置を維持
+- **極小バンドル** — gzip 後 5KB 未満
+
+## 基本的な例
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual'
+
+function VirtualList() {
+  const parentRef = React.useRef<HTMLDivElement>(null)
+
+  const virtualizer = useVirtualizer({
+    count: 10000,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 35,
+  })
+
+  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>
+  )
+}
+```
+
+## TanStack Virtual を使うべき場面
+
+- 100 件以上のアイテムを含むリスト
+- 多数の行を持つテーブル
+- チャット・メッセージインターフェース
+- 無限スクロールフィード
+- 大規模な動的データセットを含む任意の UI

package/template/content/virtual/zh-hans/installation.md

@@ -0,0 +1,57 @@
+---
+title: 安装
+description: 如何在项目中安装 TanStack Virtual
+---
+
+# 安装
+
+## React
+
+```bash
+npm install @tanstack/react-virtual
+```
+
+```bash
+pnpm add @tanstack/react-virtual
+```
+
+```bash
+yarn add @tanstack/react-virtual
+```
+
+```bash
+bun add @tanstack/react-virtual
+```
+
+## Vue
+
+```bash
+npm install @tanstack/vue-virtual
+```
+
+## Solid
+
+```bash
+npm install @tanstack/solid-virtual
+```
+
+## Svelte
+
+```bash
+npm install @tanstack/svelte-virtual
+```
+
+## 环境要求
+
+- React 18+ / Vue 3+ / Solid 1.6+ / Svelte 4+
+- 具有固定高度（或水平列表的固定宽度）的滚动容器
+
+## 包体积
+
+TanStack Virtual 非常轻量：
+
+| 包 | 大小（gzip） |
+|---------|---------------|
+| `@tanstack/virtual-core` | ~2.5 KB |
+| `@tanstack/react-virtual` | ~3.5 KB |
+| `@tanstack/vue-virtual` | ~3.5 KB |

package/template/content/virtual/zh-hans/overview.md

@@ -0,0 +1,74 @@
+---
+title: TanStack Virtual 概览
+description: 无头 UI，以 60FPS 虚拟化大型元素列表
+---
+
+# TanStack Virtual
+
+TanStack Virtual 提供无头的虚拟化工具，用于处理长列表元素。它根据滚动位置处理渲染哪些项目的逻辑，同时你保留对标记和样式的完全控制。
+
+## 为什么需要虚拟化？
+
+一次渲染数千个 DOM 节点会导致严重的性能问题。虚拟化通过仅渲染当前在视口中可见的项目以及少量的预渲染缓冲来解决这个问题。
+
+## 特性
+
+- **框架无关** — 支持 React、Vue、Solid、Svelte 和原生 JS
+- **垂直和水平** — 任意方向虚拟化列表
+- **网格虚拟化** — 结合垂直和水平虚拟化器实现网格
+- **动态行高** — 支持可变大小的项目及测量
+- **固定项目** — 将项目固定在滚动区域的顶部或底部
+- **滚动恢复** — 在导航中保持滚动位置
+- **极小的包体积** — gzip 后不到 5KB
+
+## 基本示例
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual'
+
+function VirtualList() {
+  const parentRef = React.useRef<HTMLDivElement>(null)
+
+  const virtualizer = useVirtualizer({
+    count: 10000,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 35,
+  })
+
+  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>
+  )
+}
+```
+
+## 何时使用 TanStack Virtual
+
+- 包含 100+ 项的列表
+- 多行的表格
+- 聊天/消息界面
+- 无限滚动的信息流
+- 任何包含大量动态数据集的 UI