Virtualization Table

Handle large datasets efficiently with virtual scrolling.

Preview with Controlled State

	Name	Category	Price	Stock	Status

Virtualized Table State

Live view of the virtualized table state with 10,000 total items

Search Query:None

Total Items:10,000

Filtered Items:10,000

Active Filters:0 (Search Only)

Expanded Rows:0

Sorting:None

Page:1 (Size: 100)

Hidden Columns:0

Pinned Columns:0 Left, 0 Right

View Full State Object

Sorting:

[]

Expanded Rows:

{}

Pagination:

{
  "pageIndex": 0,
  "pageSize": 100
}

Column Visibility:

{}

Column Pinning:

{
  "left": [],
  "right": []
}

Introduction

The Virtualization Table uses virtual scrolling to efficiently render large datasets (1000+ rows) by only rendering visible rows. This provides smooth performance even with 10,000+ rows.

Installation

Add the required components:

npx shadcn@latest add table input button dropdown-menu scroll-area

Add dependencies:

npm install @tanstack/react-table @tanstack/react-virtual

Copy the DataTable components into your project. See the Installation Guide for detailed instructions.

Prerequisites

We are going to build a table to show products with virtualization. Here’s what our data looks like:

1
type Product = {
2
  id: string
3
  name: string
4
  category: string
5
  price: number
6
  stock: number
7
  status: "in-stock" | "low-stock" | "out-of-stock"
8
}
9

10
// Generate large dataset
11
const largeData: Product[] = Array.from({ length: 10000 }, (_, i) => ({
12
  id: `product-${i + 1}`,
13
  name: `Product ${i + 1}`,
14
  category: "Electronics",
15
  price: Math.floor(Math.random() * 500) + 10,
16
  stock: Math.floor(Math.random() * 150),
17
  status: "in-stock",
18
}))

Basic Table with Virtualization

Let’s start by building a virtualized table.

Column Definitions

First, we’ll define our columns.

1
"use client"
2

3
import {
4
  DataTableColumnHeader,
5
  DataTableColumnTitle,
6
  DataTableColumnSortMenu,
7
} from "@/components/niko-table/components"
8
import type { DataTableColumnDef } from "@/components/niko-table/types"
9

10
export type Product = {
11
  id: string
12
  name: string
13
  category: string
14
  price: number
15
  stock: number
16
  status: "in-stock" | "low-stock" | "out-of-stock"
17
}
18

19
export const columns: DataTableColumnDef<Product>[] = [
20
  {
21
    accessorKey: "name",
22
    header: () => (
23
      <DataTableColumnHeader>
24
        <DataTableColumnTitle />
25
        <DataTableColumnSortMenu />
26
      </DataTableColumnHeader>
27
    ),
28
    meta: { label: "Name" },
29
    cell: ({ row }) => (
30
      <div className="font-medium">{row.getValue("name")}</div>
31
    ),
32
  },
33
  {
34
    accessorKey: "category",
35
    header: () => (
36
      <DataTableColumnHeader>
37
        <DataTableColumnTitle />
38
        <DataTableColumnSortMenu />
39
      </DataTableColumnHeader>
40
    ),
41
    meta: { label: "Category" },
42
  },
43
  {
44
    accessorKey: "price",
45
    header: () => (
46
      <DataTableColumnHeader>
47
        <DataTableColumnTitle />
48
        <DataTableColumnSortMenu />
49
      </DataTableColumnHeader>
50
    ),
51
    meta: { label: "Price" },
52
    cell: ({ row }) => {
53
      const price = row.getValue("price") as number
54
      return <div className="font-mono">${price.toFixed(2)}</div>
55
    },
56
  },
57
  {
58
    accessorKey: "stock",
59
    header: () => (
60
      <DataTableColumnHeader>
61
        <DataTableColumnTitle />
62
        <DataTableColumnSortMenu />
63
      </DataTableColumnHeader>
64
    ),
65
    meta: { label: "Stock" },
66
  },
67
  {
68
    accessorKey: "status",
69
    header: () => (
70
      <DataTableColumnHeader>
71
        <DataTableColumnTitle />
72
        <DataTableColumnSortMenu />
73
      </DataTableColumnHeader>
74
    ),
75
    meta: { label: "Status" },
76
  },
77
]

`<DataTable />` component

Next, we’ll create a virtualized table.

1
"use client"
2

3
import {
4
  DataTableRoot,
5
  DataTable,
6
  DataTableVirtualizedHeader,
7
  DataTableVirtualizedBody,
8
  DataTableVirtualizedEmptyBody,
9
  DataTableVirtualizedSkeleton,
10
} from "@/components/niko-table/core"
11
import {
12
  DataTableToolbarSection,
13
  DataTablePagination,
14
  DataTableSearchFilter,
15
  DataTableViewMenu,
16
  DataTableColumnHeader,
17
  DataTableColumnTitle,
18
  DataTableColumnSortMenu,
19
} from "@/components/niko-table/components"
20
import type { DataTableColumnDef } from "@/components/niko-table/types"
21

22
type Product = {
23
  id: string
24
  name: string
25
  category: string
26
  price: number
27
  stock: number
28
  status: "in-stock" | "low-stock" | "out-of-stock"
29
}
30

31
const columns: DataTableColumnDef<Product>[] = [
32
  {
33
    accessorKey: "name",
34
    header: () => (
35
      <DataTableColumnHeader>
36
        <DataTableColumnTitle />
37
        <DataTableColumnSortMenu />
38
      </DataTableColumnHeader>
39
    ),
40
    meta: { label: "Name" },
41
    cell: ({ row }) => (
42
      <div className="font-medium">{row.getValue("name")}</div>
43
    ),
44
  },
45
  {
46
    accessorKey: "category",
47
    header: () => (
48
      <DataTableColumnHeader>
49
        <DataTableColumnTitle />
50
        <DataTableColumnSortMenu />
51
      </DataTableColumnHeader>
52
    ),
53
    meta: { label: "Category" },
54
  },
55
  {
56
    accessorKey: "price",
57
    header: () => (
58
      <DataTableColumnHeader>
59
        <DataTableColumnTitle />
60
        <DataTableColumnSortMenu />
61
      </DataTableColumnHeader>
62
    ),
63
    meta: { label: "Price" },
64
    cell: ({ row }) => {
65
      const price = row.getValue("price") as number
66
      return <div className="font-mono">${price.toFixed(2)}</div>
67
    },
68
  },
69
  {
70
    accessorKey: "stock",
71
    header: () => (
72
      <DataTableColumnHeader>
73
        <DataTableColumnTitle />
74
        <DataTableColumnSortMenu />
75
      </DataTableColumnHeader>
76
    ),
77
    meta: { label: "Stock" },
78
  },
79
  {
80
    accessorKey: "status",
81
    header: () => (
82
      <DataTableColumnHeader>
83
        <DataTableColumnTitle />
84
        <DataTableColumnSortMenu />
85
      </DataTableColumnHeader>
86
    ),
87
    meta: { label: "Status" },
88
  },
89
]
90

91
export function VirtualizationTable({ data }: { data: Product[] }) {
92
  return (
93
    <DataTableRoot
94
      data={data}
95
      columns={columns}
96
      config={{
97
        enablePagination: true,
98
        enableSorting: true,
99
        enableFilters: true,
100
      }}
101
    >
102
      <DataTableToolbarSection>
103
        <DataTableSearchFilter placeholder="Search products..." />
104
        <DataTableViewMenu />
105
      </DataTableToolbarSection>
106

107
      <DataTable height={600} className="rounded-lg border">
108
        <DataTableVirtualizedHeader />
109
        <DataTableVirtualizedBody>
110
          <DataTableVirtualizedSkeleton rows={5} />
111
          <DataTableVirtualizedEmptyBody />
112
        </DataTableVirtualizedBody>
113
      </DataTable>
114

115
      <DataTablePagination pageSizeOptions={[50, 100, 200, 500]} />
116
    </DataTableRoot>
117
  )
118
}

Virtualized Components

DataTableVirtualizedHeader

Virtualized version of the table header.

1
<DataTableVirtualizedHeader />

DataTableVirtualizedBody

Virtualized version of the table body. Only renders visible rows.

1
<DataTableVirtualizedBody>
2
  <DataTableVirtualizedEmptyBody />
3
</DataTableVirtualizedBody>

DataTableVirtualizedEmptyBody

Empty state component for virtualized tables.

1
<DataTableVirtualizedEmptyBody />

DataTableVirtualizedSkeleton

Skeleton loading state for virtualized tables. Shows skeleton rows during data fetching.

1
<DataTableVirtualizedBody>
2
  <DataTableVirtualizedSkeleton rows={5} />
3
  <DataTableVirtualizedEmptyBody />
4
</DataTableVirtualizedBody>

DataTableVirtualizedLoading

Simple loading spinner for virtualized tables. Shows a centered loading indicator.

1
<DataTableVirtualizedBody>
2
  <DataTableVirtualizedLoading />
3
  <DataTableVirtualizedEmptyBody />
4
</DataTableVirtualizedBody>

Note: Use DataTableVirtualizedSkeleton for a more detailed loading state that mimics the table structure, or DataTableVirtualizedLoading for a simple spinner.

Required: Fixed Height

Virtualization requires a fixed height on the DataTable component:

1
<DataTable height={600} className="rounded-lg border">
2
  <DataTableVirtualizedHeader />
3
  <DataTableVirtualizedBody>
4
    <DataTableVirtualizedSkeleton rows={5} />
5
    <DataTableVirtualizedEmptyBody />
6
  </DataTableVirtualizedBody>
7
</DataTable>

Controlled State

Manage table state externally for full control:

1
import { useState } from "react"
2
import type {
3
  SortingState,
4
  ColumnFiltersState,
5
  PaginationState,
6
} from "@tanstack/react-table"
7

8
export function ControlledVirtualizationTable({ data }: { data: Product[] }) {
9
  const [sorting, setSorting] = useState<SortingState>([])
10
  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
11
  const [pagination, setPagination] = useState<PaginationState>({
12
    pageIndex: 0,
13
    pageSize: 50,
14
  })
15
  const [globalFilter, setGlobalFilter] = useState("")
16

17
  return (
18
    <DataTableRoot
19
      data={data}
20
      columns={columns}
21
      config={{
22
        enablePagination: true,
23
        enableSorting: true,
24
        enableFilters: true,
25
      }}
26
      state={{
27
        sorting,
28
        columnFilters,
29
        pagination,
30
        globalFilter,
31
      }}
32
      onSortingChange={setSorting}
33
      onColumnFiltersChange={setColumnFilters}
34
      onPaginationChange={setPagination}
35
      onGlobalFilterChange={setGlobalFilter}
36
    >
37
      <DataTableToolbarSection>
38
        <DataTableSearchFilter placeholder="Search products..." />
39
        <DataTableViewMenu />
40
      </DataTableToolbarSection>
41

42
      <DataTable height={600} className="rounded-lg border">
43
        <DataTableVirtualizedHeader />
44
        <DataTableVirtualizedBody>
45
          <DataTableVirtualizedSkeleton rows={5} />
46
          <DataTableVirtualizedEmptyBody />
47
        </DataTableVirtualizedBody>
48
      </DataTable>
49

50
      <DataTablePagination pageSizeOptions={[50, 100, 200, 500]} />
51
    </DataTableRoot>
52
  )
53
}

When to Use

✅ Use Virtualization Table when:

You have 1000+ rows
Performance is critical
Users need smooth scrolling
Dataset is too large for regular pagination

❌ Don’t use Virtualization Table when:

You have < 1000 rows (use Basic Table)
You need variable row heights (virtualization works best with fixed heights)
You need complex row interactions (virtualization has limitations)

Performance Tips

Fixed height required: Always set a fixed height on DataTable
Consistent row heights: Virtualization works best with uniform row heights
Memoize columns: Wrap column definitions in useMemo
Large page sizes: Use larger page sizes (50-500) for better virtualization

Next Steps

Basic Table - For smaller datasets
Advanced Table - Combine with other features

Virtualization Table

Introduction

Installation

Prerequisites

Basic Table with Virtualization

Column Definitions

`<DataTable />` component

Virtualized Components

DataTableVirtualizedHeader

DataTableVirtualizedBody

DataTableVirtualizedEmptyBody

DataTableVirtualizedSkeleton

DataTableVirtualizedLoading

Required: Fixed Height

Controlled State

When to Use

Performance Tips

Next Steps

Getting Started

Niko Table

Examples

Contributing

Virtualization Table

Introduction

Installation

Prerequisites

Basic Table with Virtualization

Column Definitions

<DataTable /> component

Virtualized Components

DataTableVirtualizedHeader

DataTableVirtualizedBody

DataTableVirtualizedEmptyBody

DataTableVirtualizedSkeleton

DataTableVirtualizedLoading

Required: Fixed Height

Controlled State

When to Use

Performance Tips

Next Steps

Getting Started

Niko Table

Examples

Contributing

`<DataTable />` component