Row virtualization

Prop enableVirtualization — engine behaviour, default false.

Guide

When to use it

Large grids — thousands of rows — that must stay at 60fps. Virtualization paints only the rows in the viewport (plus a small overscan), keeping the DOM bounded no matter the row count.

How it works

Backed by @tanstack/react-virtual. boolean | { overscan, estimateRowSize, estimateColumnSize }. It also bounds the scroll box, so enableStickyHeader isn't needed alongside it.

<BstTableMui data={rows} columns={columns} getRowId={(r) => r.id}
  enableVirtualization={{ overscan: 8 }} />

Gotchas

• It yields to master-detail, grouping, cell spanning and row pinning — those render un-windowed because they need full DOM.
• Give estimateRowSize a realistic value for smooth scrollbars with variable row heights.
• Always shown in the settings sheet ("Performance") so an end-user can switch it on for a big grid.

Live example

Example source

import React from 'react'
import { BstTableMui } from '@bloomskill/table-mui'
import type { BstTableColumn } from '@bloomskill/table-engine'
import '@bloomskill/table-engine/styles.css'

type Row = { id: string; name: string; team: string; role: string; score: number }
const seed: Row[] = [
  { id: '1', name: 'Ada Lovelace',   team: 'Platform', role: 'Engineer', score: 92 },
  { id: '2', name: 'Alan Turing',    team: 'Research', role: 'Scientist', score: 88 },
  { id: '3', name: 'Grace Hopper',   team: 'Platform', role: 'Engineer', score: 95 },
  { id: '4', name: 'Katherine J.',   team: 'Research', role: 'Analyst',  score: 90 },
  { id: '5', name: 'Edsger Dijkstra',team: 'Platform', role: 'Architect',score: 84 },
]
const columns: BstTableColumn<Row>[] = [
  { id: 'name',  accessorKey: 'name',  header: 'Name' },
  { id: 'team',  accessorKey: 'team',  header: 'Team' },
  { id: 'role',  accessorKey: 'role',  header: 'Role' },
  { id: 'score', accessorKey: 'score', header: 'Score', sortFn: 'basic' },
]

const many: Row[] = Array.from({ length: 500 }, (_, i) => ({
  ...seed[i % seed.length], id: String(i + 1), score: 60 + (i % 40),
}))
export default function App() {
  return (
    <BstTableMui data={many} columns={columns} getRowId={(r) => r.id}
      enableVirtualization={{ overscan: 8 }} pagination={false} />
  )
}

Loading live example…

Overview

Layer	enable* (engine, resolved in useBstTable)
Type	boolean | {overscan,estimateRowSize,estimateColumnSize}
Default	false
Maps to	custom render feature — @tanstack/react-virtual; paints only rows in the viewport (resolveVirtualization pure helper, useVirtualizer in BstTable). Yields to (renders un-windowed under) master-detail / grouping / cell spanning / row pinning — see virtualizationBypassReason. In settings ("Performance", always shown so an end-user can switch it on for a large grid)
Status	✅ done
Since	v0.33.0
Settings sheet	Performance

Row virtualization — render only the rows inside the scroll viewport (plus overscan), so a 10k / 1M-row grid stays fast with a bounded DOM. Pass true, or an object to tune it ({ overscan, estimateRowSize, estimateColumnSize } — an object implies enabled, §12). Opt-in. Default false. The scroll box needs a bounded height — one is applied by default and can be overridden via styles.root. Yields to master-detail, grouping, cell spanning and row pinning (the grid renders un-windowed when one of those is on). Built on @tanstack/react-virtual.

Enable it

<BstTableMui
  data={rows}
  columns={columns}
  enableVirtualization={/* boolean | {overscan,estimateRowSize,estimateColumnSize} */}
/>

Swap BstTableMui for BstTableShadcn (and the CSS import) for the shadcn skin — same props.

Options

Option	Notes
VirtualizationOptions	Related prop for this feature.

Behavior & interactions

• Conflicts with enableExpanding — the grid renders un-windowed (yields) while master-detail is on.
• Conflicts with enableGrouping — the grid renders un-windowed (yields) while grouping is on.
• Conflicts with enableCellSpanning — the grid renders un-windowed (yields) while cell spanning is on.
• Conflicts with enableRowPinning — the grid renders un-windowed (yields) while row pinning is on.
• Paints only the visible rows for large datasets. Object form tunes overscan / estimateRowSize / estimateColumnSize. Needs a bounded scroll-box height (applied by default; override via styles.root).

Spec coverage

Spec codes (A1, C2, X8, …) are Bst-Table's internal requirement IDs from the capability matrix; P0–P2 mark the delivery phase. They are traceability tags, not part of the public API.

• D1 · Row & column virtualization — ✅ built. enableVirtualization (+ enableColumnVirtualization) on @tanstack/react-virtual — windowed rows (dynamic measure) + columns, sticky header, bounded DOM; yields to master-detail / grouping / cell spanning / row pinning. Tested (virtualization.test.tsx)