Virtualization Table

Handle large datasets efficiently with virtual scrolling.

1
"use client"
2

3
import * as React from "react"
4
import { DataTableRoot } from "@/components/niko-table/core/data-table-root"
5
import { DataTable } from "@/components/niko-table/core/data-table"
6
import {
7
  DataTableVirtualizedHeader,
8
  DataTableVirtualizedBody,
9
  DataTableVirtualizedEmptyBody,
10
} from "@/components/niko-table/core/data-table-virtualized-structure"
11
import { DataTableColumnHeader } from "@/components/niko-table/components/data-table-column-header"
12
import { DataTableColumnTitle } from "@/components/niko-table/components/data-table-column-title"
13
import { DataTableColumnSortMenu } from "@/components/niko-table/components/data-table-column-sort"
14
import {
15
  DataTableEmptyIcon,
16
  DataTableEmptyMessage,
17
  DataTableEmptyFilteredMessage,
18
  DataTableEmptyTitle,
19
  DataTableEmptyDescription,
20
} from "@/components/niko-table/components/data-table-empty-state"
21
import { DataTablePagination } from "@/components/niko-table/components/data-table-pagination"
22
import { DataTableSearchFilter } from "@/components/niko-table/components/data-table-search-filter"
23
import { DataTableToolbarSection } from "@/components/niko-table/components/data-table-toolbar-section"
24
import { DataTableViewMenu } from "@/components/niko-table/components/data-table-view-menu"
25
import {
26
  FILTER_VARIANTS,
27
  SYSTEM_COLUMN_IDS,
28
} from "@/components/niko-table/lib/constants"
29
import type { DataTableColumnDef } from "@/components/niko-table/types"
30
import { Badge } from "@/components/ui/badge"
31
import { Button } from "@/components/ui/button"
32
import { ChevronRight, ChevronDown, UserSearch, SearchX } from "lucide-react"
33

34
// Example data type
35
interface Product {
36
  id: string
37
  name: string
38
  category: string
39
  brand: string
40
  price: number
41
  stock: number
42
  rating: number
43
  revenue: number
44
  status: "in-stock" | "low-stock" | "out-of-stock"
45
  releaseDate: Date
46
}
47

48
// Generate large dataset for virtualization demo
49
const generateLargeData = (count: number): Product[] => {
50
  const categories = [
51
    "Electronics",
52
    "Clothing",
53
    "Food",
54
    "Books",
55
    "Sports",
56
    "Home",
57
    "Toys",
58
    "Beauty",
59
  ]
60
  const brands = [
61
    "Apple",
62
    "Samsung",
63
    "Nike",
64
    "Adidas",
65
    "Sony",
66
    "LG",
67
    "Dell",
68
    "HP",
69
  ]
70

71
  return Array.from({ length: count }, (_, i) => {
72
    const stock = Math.floor(Math.random() * 150)
73
    const price = Math.floor(Math.random() * 500) + 10
74
    return {
75
      id: `product-${i + 1}`,
76
      name: `Product ${i + 1}`,
77
      category: categories[Math.floor(Math.random() * categories.length)],
78
      brand: brands[Math.floor(Math.random() * brands.length)],
79
      price,
80
      stock,
81
      rating: Math.floor(Math.random() * 5) + 1,
82
      revenue: price * stock,
83
      status:
84
        stock === 0 ? "out-of-stock" : stock < 20 ? "low-stock" : "in-stock",
85
      releaseDate: new Date(
86
        2024,
87
        Math.floor(Math.random() * 12),
88
        Math.floor(Math.random() * 28) + 1,
89
      ),
90
    }
91
  })
92
}
93

94
const largeData = generateLargeData(10000) // 10,000 items
95

96
// Expanded content component for product details
97
function ProductDetails({ product }: { product: Product }) {
98
  return (
99
    <div className="bg-muted/30 p-4">
100
      <h3 className="font-semibold">Product Details</h3>
101
      <div className="grid grid-cols-1 gap-4 text-sm sm:grid-cols-2">
102
        <div>
103
          <div>
104
            <span className="text-muted-foreground">ID:</span> {product.id}
105
          </div>
106
          <div>
107
            <span className="text-muted-foreground">Category:</span>{" "}
108
            {product.category}
109
          </div>
110
        </div>
111
        <div>
112
          <div>
113
            <span className="text-muted-foreground">Price:</span> ${""}
114
            {product.price.toFixed(2)}
115
          </div>
116
          <div>
117
            <span className="text-muted-foreground">Stock:</span>{" "}
118
            {product.stock}
119
          </div>
120
        </div>
121
      </div>
122
    </div>
123
  )
124
}
125

126
export default function VirtualizedTableExample() {
127
  const columns: DataTableColumnDef<Product>[] = React.useMemo(
128
    () => [
129
      {
130
        id: SYSTEM_COLUMN_IDS.EXPAND,
131
        header: () => null,
132
        cell: ({ row }) => {
133
          if (!row.getCanExpand()) return null
134
          return (
135
            <Button
136
              variant="ghost"
137
              size="sm"
138
              onClick={row.getToggleExpandedHandler()}
139
              className="h-6 w-6 p-0 hover:bg-accent"
140
            >
141
              {row.getIsExpanded() ? (
142
                <ChevronDown className="h-3.5 w-3.5" />
143
              ) : (
144
                <ChevronRight className="h-3.5 w-3.5" />
145
              )}
146
            </Button>
147
          )
148
        },
149
        size: 50,
150
        enableSorting: false,
151
        enableHiding: false,
152
        meta: {
153
          expandedContent: (product: Product) => (
154
            <ProductDetails product={product} />
155
          ),
156
        },
157
      },
158
      {
159
        accessorKey: "name",
160
        header: () => (
161
          <DataTableColumnHeader>
162
            <DataTableColumnTitle title="Name" />
163
            <DataTableColumnSortMenu />
164
          </DataTableColumnHeader>
165
        ),
166
        cell: ({ row }) => (
167
          <div className="font-medium">{row.getValue("name")}</div>
168
        ),
169
      },
170
      {
171
        accessorKey: "category",
172
        header: () => (
173
          <DataTableColumnHeader>
174
            <DataTableColumnTitle title="Category" />
175
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.TEXT} />
176
          </DataTableColumnHeader>
177
        ),
178
        cell: ({ row }) => (
179
          <div className="capitalize">{row.getValue("category")}</div>
180
        ),
181
      },
182
      {
183
        accessorKey: "price",
184
        header: () => (
185
          <DataTableColumnHeader>
186
            <DataTableColumnTitle title="Price" />
187
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.NUMBER} />
188
          </DataTableColumnHeader>
189
        ),
190
        cell: ({ row }) => {
191
          const price = row.getValue("price") as number
192
          return <div className="font-mono">${price.toFixed(2)}</div>
193
        },
194
      },
195
      {
196
        accessorKey: "stock",
197
        header: () => (
198
          <DataTableColumnHeader>
199
            <DataTableColumnTitle title="Stock" />
200
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.NUMBER} />
201
          </DataTableColumnHeader>
202
        ),
203
        cell: ({ row }) => (
204
          <div className="text-right">{row.getValue("stock")}</div>
205
        ),
206
      },
207
      {
208
        accessorKey: "status",
209
        header: () => (
210
          <DataTableColumnHeader>
211
            <DataTableColumnTitle title="Status" />
212
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.TEXT} />
213
          </DataTableColumnHeader>
214
        ),
215
        cell: ({ row }) => {
216
          const status = row.getValue("status") as string
217
          return (
218
            <Badge
219
              variant={
220
                status === "in-stock"
221
                  ? "default"
222
                  : status === "low-stock"
223
                    ? "secondary"
224
                    : "destructive"
225
              }
226
            >
227
              {status}
228
            </Badge>
229
          )
230
        },
231
        filterFn: (row, id, value: string[]) => {
232
          return value.includes(row.getValue(id))
233
        },
234
      },
235
      {
236
        accessorKey: "brand",
237
        header: () => (
238
          <DataTableColumnHeader>
239
            <DataTableColumnTitle title="Brand" />
240
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.TEXT} />
241
          </DataTableColumnHeader>
242
        ),
243
        cell: ({ row }) => (
244
          <div className="capitalize">{row.getValue("brand")}</div>
245
        ),
246
      },
247
      {
248
        accessorKey: "rating",
249
        header: () => (
250
          <DataTableColumnHeader>
251
            <DataTableColumnTitle title="Rating" />
252
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.NUMBER} />
253
          </DataTableColumnHeader>
254
        ),
255
        cell: ({ row }) => {
256
          const rating = row.getValue("rating") as number
257
          return (
258
            <div className="flex items-center gap-1">
259
              <span>{rating}</span>
260
              <span className="text-yellow-500">★</span>
261
            </div>
262
          )
263
        },
264
      },
265
      {
266
        accessorKey: "revenue",
267
        header: () => (
268
          <DataTableColumnHeader>
269
            <DataTableColumnTitle title="Revenue" />
270
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.NUMBER} />
271
          </DataTableColumnHeader>
272
        ),
273
        cell: ({ row }) => {
274
          const revenue = row.getValue("revenue") as number
275
          return <div className="font-mono">${revenue.toLocaleString()}</div>
276
        },
277
      },
278
      {
279
        accessorKey: "releaseDate",
280
        header: () => (
281
          <DataTableColumnHeader>
282
            <DataTableColumnTitle title="Release Date" />
283
            <DataTableColumnSortMenu />
284
          </DataTableColumnHeader>
285
        ),
286
        cell: ({ row }) => {
287
          const date = row.getValue("releaseDate") as Date
288
          return <span>{date.toLocaleDateString()}</span>
289
        },
290
      },
291
    ],
292
    [],
293
  )
294

295
  return (
296
    <DataTableRoot
297
      data={largeData}
298
      columns={columns}
299
      config={{
300
        enableExpanding: true,
301
        initialPageSize: 50,
302
      }}
303
      getRowCanExpand={row => row.original.stock > 0}
304
    >
305
      <DataTableToolbarSection>
306
        <DataTableSearchFilter placeholder="Search products..." />
307
        <DataTableViewMenu />
308
      </DataTableToolbarSection>
309
      <DataTable height={600} className="rounded-lg border">
310
        <DataTableVirtualizedHeader />
311
        <DataTableVirtualizedBody>
312
          <DataTableVirtualizedEmptyBody>
313
            <DataTableEmptyMessage>
314
              <DataTableEmptyIcon>
315
                <UserSearch className="size-12" />
316
              </DataTableEmptyIcon>
317
              <DataTableEmptyTitle>No products found</DataTableEmptyTitle>
318
              <DataTableEmptyDescription>
319
                There are no products to display at this time.
320
              </DataTableEmptyDescription>
321
            </DataTableEmptyMessage>
322
            <DataTableEmptyFilteredMessage>
323
              <DataTableEmptyIcon>
324
                <SearchX className="size-12" />
325
              </DataTableEmptyIcon>
326
              <DataTableEmptyTitle>No matches found</DataTableEmptyTitle>
327
              <DataTableEmptyDescription>
328
                Try adjusting your search to find what you&apos;re looking for.
329
              </DataTableEmptyDescription>
330
            </DataTableEmptyFilteredMessage>
331
          </DataTableVirtualizedEmptyBody>
332
        </DataTableVirtualizedBody>
333
      </DataTable>
334
      <DataTablePagination pageSizeOptions={[50, 100, 200, 500]} />
335
    </DataTableRoot>
336
  )
337
}

	Name	Category	Price	Stock	Status	Brand	Rating	Revenue	Release Date

Preview with Controlled State

Open in

1
"use client"
2

3
import * as React from "react"
4
import { useState } from "react"
5
import type {
6
  PaginationState,
7
  SortingState,
8
  ColumnFiltersState,
9
  VisibilityState,
10
  ExpandedState,
11
  ColumnPinningState,
12
} from "@tanstack/react-table"
13
import { DataTableRoot } from "@/components/niko-table/core/data-table-root"
14
import { DataTable } from "@/components/niko-table/core/data-table"
15
import {
16
  DataTableVirtualizedHeader,
17
  DataTableVirtualizedBody,
18
  DataTableVirtualizedEmptyBody,
19
} from "@/components/niko-table/core/data-table-virtualized-structure"
20
import { DataTableColumnActions } from "@/components/niko-table/components/data-table-column-actions"
21
import { DataTableColumnHeader } from "@/components/niko-table/components/data-table-column-header"
22
import { DataTableColumnTitle } from "@/components/niko-table/components/data-table-column-title"
23
import {
24
  DataTableColumnSortMenu,
25
  DataTableColumnSortOptions,
26
} from "@/components/niko-table/components/data-table-column-sort"
27
import {
28
  DataTableEmptyIcon,
29
  DataTableEmptyMessage,
30
  DataTableEmptyFilteredMessage,
31
  DataTableEmptyTitle,
32
  DataTableEmptyDescription,
33
} from "@/components/niko-table/components/data-table-empty-state"
34
import { DataTablePagination } from "@/components/niko-table/components/data-table-pagination"
35
import { DataTableSearchFilter } from "@/components/niko-table/components/data-table-search-filter"
36
import { DataTableToolbarSection } from "@/components/niko-table/components/data-table-toolbar-section"
37
import { DataTableViewMenu } from "@/components/niko-table/components/data-table-view-menu"
38
import {
39
  FILTER_VARIANTS,
40
  SYSTEM_COLUMN_IDS,
41
} from "@/components/niko-table/lib/constants"
42
import type { DataTableColumnDef } from "@/components/niko-table/types"
43
import { Badge } from "@/components/ui/badge"
44
import { Button } from "@/components/ui/button"
45
import { ChevronRight, ChevronDown, UserSearch, SearchX } from "lucide-react"
46
import {
47
  Card,
48
  CardAction,
49
  CardContent,
50
  CardDescription,
51
  CardHeader,
52
  CardTitle,
53
} from "@/components/ui/card"
54

55
// Example data type
56
interface Product {
57
  id: string
58
  name: string
59
  category: string
60
  brand: string
61
  price: number
62
  stock: number
63
  rating: number
64
  revenue: number
65
  status: "in-stock" | "low-stock" | "out-of-stock"
66
  releaseDate: Date
67
}
68

69
// Generate large dataset for virtualization demo
70
const generateLargeData = (count: number): Product[] => {
71
  const categories = [
72
    "Electronics",
73
    "Clothing",
74
    "Food",
75
    "Books",
76
    "Sports",
77
    "Home",
78
    "Toys",
79
    "Beauty",
80
  ]
81
  const brands = [
82
    "Apple",
83
    "Samsung",
84
    "Nike",
85
    "Adidas",
86
    "Sony",
87
    "LG",
88
    "Dell",
89
    "HP",
90
  ]
91

92
  return Array.from({ length: count }, (_, i) => {
93
    const stock = Math.floor(Math.random() * 150)
94
    const price = Math.floor(Math.random() * 500) + 10
95
    return {
96
      id: `product-${i + 1}`,
97
      name: `Product ${i + 1}`,
98
      category: categories[Math.floor(Math.random() * categories.length)],
99
      brand: brands[Math.floor(Math.random() * brands.length)],
100
      price,
101
      stock,
102
      rating: Math.floor(Math.random() * 5) + 1,
103
      revenue: price * stock,
104
      status:
105
        stock === 0 ? "out-of-stock" : stock < 20 ? "low-stock" : "in-stock",
106
      releaseDate: new Date(
107
        2024,
108
        Math.floor(Math.random() * 12),
109
        Math.floor(Math.random() * 28) + 1,
110
      ),
111
    }
112
  })
113
}
114

115
const largeData = generateLargeData(10000) // 10,000 items
116

117
// Expanded content component for product details
118
function ProductDetails({ product }: { product: Product }) {
119
  return (
120
    <div className="bg-muted/30 p-4">
121
      <h3 className="font-semibold">Product Details</h3>
122
      <div className="grid grid-cols-1 gap-4 text-sm sm:grid-cols-2">
123
        <div>
124
          <div>
125
            <span className="text-muted-foreground">ID:</span> {product.id}
126
          </div>
127
          <div>
128
            <span className="text-muted-foreground">Category:</span>{" "}
129
            {product.category}
130
          </div>
131
        </div>
132
        <div>
133
          <div>
134
            <span className="text-muted-foreground">Price:</span> ${""}
135
            {product.price.toFixed(2)}
136
          </div>
137
          <div>
138
            <span className="text-muted-foreground">Stock:</span>{" "}
139
            {product.stock}
140
          </div>
141
        </div>
142
      </div>
143
    </div>
144
  )
145
}
146

147
export default function VirtualizedTableStateExample() {
148
  // Controlled state management for all table state
149
  const [data] = useState<Product[]>(largeData)
150
  const [globalFilter, setGlobalFilter] = useState<string | object>("")
151
  const [sorting, setSorting] = useState<SortingState>([])
152
  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
153
  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({})
154
  const [pagination, setPagination] = useState<PaginationState>({
155
    pageIndex: 0,
156
    pageSize: 100, // Larger page size for virtualization
157
  })
158
  const [expanded, setExpanded] = useState<ExpandedState>({})
159
  const [columnPinning, setColumnPinning] = useState<ColumnPinningState>({
160
    left: [],
161
    right: [],
162
  })
163

164
  const columns: DataTableColumnDef<Product>[] = React.useMemo(
165
    () => [
166
      {
167
        id: SYSTEM_COLUMN_IDS.EXPAND,
168
        header: () => null,
169
        cell: ({ row }) => {
170
          if (!row.getCanExpand()) return null
171
          return (
172
            <Button
173
              variant="ghost"
174
              size="sm"
175
              onClick={row.getToggleExpandedHandler()}
176
              className="h-6 w-6 p-0 hover:bg-accent"
177
            >
178
              {row.getIsExpanded() ? (
179
                <ChevronDown className="h-3.5 w-3.5" />
180
              ) : (
181
                <ChevronRight className="h-3.5 w-3.5" />
182
              )}
183
            </Button>
184
          )
185
        },
186
        size: 50,
187
        enableSorting: false,
188
        enableHiding: false,
189
        meta: {
190
          expandedContent: (product: Product) => (
191
            <ProductDetails product={product} />
192
          ),
193
        },
194
      },
195
      {
196
        accessorKey: "name",
197
        header: () => (
198
          <DataTableColumnHeader className="justify-start">
199
            <span className="mr-2 text-sm font-semibold">Name</span>
200
            <DataTableColumnSortMenu />
201
          </DataTableColumnHeader>
202
        ),
203
        cell: ({ row }) => (
204
          <div className="font-medium">{row.getValue("name")}</div>
205
        ),
206
      },
207
      {
208
        accessorKey: "category",
209
        header: () => (
210
          <DataTableColumnHeader>
211
            <DataTableColumnTitle />
212
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.TEXT} />
213
            <DataTableColumnActions>
214
              <DataTableColumnSortOptions variant={FILTER_VARIANTS.TEXT} />
215
            </DataTableColumnActions>
216
          </DataTableColumnHeader>
217
        ),
218
        cell: ({ row }) => (
219
          <div className="capitalize">{row.getValue("category")}</div>
220
        ),
221
      },
222
      {
223
        accessorKey: "price",
224
        header: () => (
225
          <DataTableColumnHeader>
226
            <DataTableColumnTitle title="Price" />
227
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.NUMBER} />
228
          </DataTableColumnHeader>
229
        ),
230
        cell: ({ row }) => {
231
          const price = row.getValue("price") as number
232
          return <div className="font-mono">${price.toFixed(2)}</div>
233
        },
234
      },
235
      {
236
        accessorKey: "stock",
237
        header: () => (
238
          <DataTableColumnHeader>
239
            <DataTableColumnTitle title="Stock" />
240
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.NUMBER} />
241
          </DataTableColumnHeader>
242
        ),
243
        cell: ({ row }) => (
244
          <div className="text-right">{row.getValue("stock")}</div>
245
        ),
246
      },
247
      {
248
        accessorKey: "status",
249
        header: () => (
250
          <DataTableColumnHeader>
251
            <DataTableColumnTitle title="Status" />
252
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.TEXT} />
253
          </DataTableColumnHeader>
254
        ),
255
        cell: ({ row }) => {
256
          const status = row.getValue("status") as string
257
          return (
258
            <Badge
259
              variant={
260
                status === "in-stock"
261
                  ? "default"
262
                  : status === "low-stock"
263
                    ? "secondary"
264
                    : "destructive"
265
              }
266
            >
267
              {status}
268
            </Badge>
269
          )
270
        },
271
        filterFn: (row, id, value: string[]) => {
272
          return value.includes(row.getValue(id))
273
        },
274
      },
275
      {
276
        accessorKey: "brand",
277
        header: () => (
278
          <DataTableColumnHeader>
279
            <DataTableColumnTitle title="Brand" />
280
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.TEXT} />
281
          </DataTableColumnHeader>
282
        ),
283
        cell: ({ row }) => (
284
          <div className="capitalize">{row.getValue("brand")}</div>
285
        ),
286
      },
287
      {
288
        accessorKey: "rating",
289
        header: () => (
290
          <DataTableColumnHeader>
291
            <DataTableColumnTitle title="Rating" />
292
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.NUMBER} />
293
          </DataTableColumnHeader>
294
        ),
295
        cell: ({ row }) => {
296
          const rating = row.getValue("rating") as number
297
          return (
298
            <div className="flex items-center gap-1">
299
              <span>{rating}</span>
300
              <span className="text-yellow-500">★</span>
301
            </div>
302
          )
303
        },
304
      },
305
      {
306
        accessorKey: "revenue",
307
        header: () => (
308
          <DataTableColumnHeader>
309
            <DataTableColumnTitle title="Revenue" />
310
            <DataTableColumnSortMenu variant={FILTER_VARIANTS.NUMBER} />
311
          </DataTableColumnHeader>
312
        ),
313
        cell: ({ row }) => {
314
          const revenue = row.getValue("revenue") as number
315
          return <div className="font-mono">${revenue.toLocaleString()}</div>
316
        },
317
      },
318
      {
319
        accessorKey: "releaseDate",
320
        header: () => (
321
          <DataTableColumnHeader>
322
            <DataTableColumnTitle title="Release Date" />
323
            <DataTableColumnSortMenu />
324
          </DataTableColumnHeader>
325
        ),
326
        cell: ({ row }) => {
327
          const date = row.getValue("releaseDate") as Date
328
          return <span>{date.toLocaleDateString()}</span>
329
        },
330
      },
331
    ],
332
    [],
333
  )
334

335
  const resetAllState = () => {
336
    setGlobalFilter("")
337
    setSorting([])
338
    setColumnFilters([])
339
    setColumnVisibility({})
340
    setPagination({ pageIndex: 0, pageSize: 100 })
341
    setExpanded({})
342
    setColumnPinning({ left: [], right: [] })
343
  }
344

345
  // Calculate filtered data for display metrics
346
  const filteredRowCount = React.useMemo(() => {
347
    let filtered = data
348

349
    // Apply global filter
350
    if (globalFilter && typeof globalFilter === "string") {
351
      filtered = filtered.filter(item =>
352
        Object.values(item).some(value =>
353
          String(value).toLowerCase().includes(globalFilter.toLowerCase()),
354
        ),
355
      )
356
    }
357

358
    return filtered.length
359
  }, [data, globalFilter])
360

361
  return (
362
    <div className="w-full space-y-4">
363
      <DataTableRoot
364
        data={data}
365
        columns={columns}
366
        config={{
367
          enableExpanding: true,
368
        }}
369
        getRowCanExpand={row => row.original.stock > 0}
370
        // Controlled state
371
        state={{
372
          globalFilter,
373
          sorting,
374
          columnFilters,
375
          columnVisibility,
376
          pagination,
377
          expanded,
378
          columnPinning,
379
        }}
380
        // State updaters
381
        onGlobalFilterChange={value => {
382
          setGlobalFilter(value)
383
          setPagination(prev => ({ ...prev, pageIndex: 0 }))
384
        }}
385
        onSortingChange={setSorting}
386
        onColumnFiltersChange={filters => {
387
          setColumnFilters(filters)
388
          setPagination(prev => ({ ...prev, pageIndex: 0 }))
389
        }}
390
        onColumnVisibilityChange={setColumnVisibility}
391
        onPaginationChange={setPagination}
392
        onExpandedChange={setExpanded}
393
        onColumnPinningChange={setColumnPinning}
394
      >
395
        <DataTableToolbarSection>
396
          <DataTableSearchFilter placeholder="Search products..." />
397
          <DataTableViewMenu />
398
        </DataTableToolbarSection>
399
        <DataTable height={600} className="rounded-lg border">
400
          <DataTableVirtualizedHeader />
401
          <DataTableVirtualizedBody>
402
            <DataTableVirtualizedEmptyBody>
403
              <DataTableEmptyMessage>
404
                <DataTableEmptyIcon>
405
                  <UserSearch className="size-12" />
406
                </DataTableEmptyIcon>
407
                <DataTableEmptyTitle>No products found</DataTableEmptyTitle>
408
                <DataTableEmptyDescription>
409
                  There are no products to display at this time.
410
                </DataTableEmptyDescription>
411
              </DataTableEmptyMessage>
412
              <DataTableEmptyFilteredMessage>
413
                <DataTableEmptyIcon>
414
                  <SearchX className="size-12" />
415
                </DataTableEmptyIcon>
416
                <DataTableEmptyTitle>No matches found</DataTableEmptyTitle>
417
                <DataTableEmptyDescription>
418
                  Try adjusting your search to find what you&apos;re looking
419
                  for.
420
                </DataTableEmptyDescription>
421
              </DataTableEmptyFilteredMessage>
422
            </DataTableVirtualizedEmptyBody>
423
          </DataTableVirtualizedBody>
424
        </DataTable>
425
        <DataTablePagination pageSizeOptions={[50, 100, 200, 500]} />
426
      </DataTableRoot>
427

428
      {/* State Display for demonstration */}
429
      <Card>
430
        <CardHeader>
431
          <CardTitle>Virtualized Table State</CardTitle>
432
          <CardDescription>
433
            Live view of the virtualized table state with{" "}
434
            {data.length.toLocaleString()} total items
435
          </CardDescription>
436
          <CardAction>
437
            <Button variant="outline" size="sm" onClick={resetAllState}>
438
              Reset All State
439
            </Button>
440
          </CardAction>
441
        </CardHeader>
442
        <CardContent className="space-y-4">
443
          <div className="grid gap-2 text-xs text-muted-foreground">
444
            <div className="flex justify-between">
445
              <span className="font-medium">Search Query:</span>
446
              <span className="text-foreground">
447
                {typeof globalFilter === "string"
448
                  ? globalFilter || "None"
449
                  : "Mixed Filters"}
450
              </span>
451
            </div>
452

453
            <div className="flex justify-between">
454
              <span className="font-medium">Total Items:</span>
455
              <span className="text-foreground">
456
                {data.length.toLocaleString()}
457
              </span>
458
            </div>
459

460
            <div className="flex justify-between">
461
              <span className="font-medium">Filtered Items:</span>
462
              <span className="text-foreground">
463
                {filteredRowCount.toLocaleString()}
464
              </span>
465
            </div>
466

467
            <div className="flex justify-between">
468
              <span className="font-medium">Active Filters:</span>
469
              <span className="text-foreground">0 (Search Only)</span>
470
            </div>
471

472
            <div className="flex justify-between">
473
              <span className="font-medium">Expanded Rows:</span>
474
              <span className="text-foreground">
475
                {Object.keys(expanded).length}
476
              </span>
477
            </div>
478

479
            <div className="flex justify-between">
480
              <span className="font-medium">Sorting:</span>
481
              <span className="text-foreground">
482
                {sorting.length > 0
483
                  ? sorting
484
                      .map(s => `${s.id} ${s.desc ? "desc" : "asc"}`)
485
                      .join(", ")
486
                  : "None"}
487
              </span>
488
            </div>
489

490
            <div className="flex justify-between">
491
              <span className="font-medium">Page:</span>
492
              <span className="text-foreground">
493
                {pagination.pageIndex + 1} (Size: {pagination.pageSize})
494
              </span>
495
            </div>
496

497
            <div className="flex justify-between">
498
              <span className="font-medium">Hidden Columns:</span>
499
              <span className="text-foreground">
500
                {
501
                  Object.values(columnVisibility).filter(v => v === false)
502
                    .length
503
                }
504
              </span>
505
            </div>
506

507
            <div className="flex justify-between">
508
              <span className="font-medium">Pinned Columns:</span>
509
              <span className="text-foreground">
510
                {columnPinning.left?.length || 0} Left,{" "}
511
                {columnPinning.right?.length || 0} Right
512
              </span>
513
            </div>
514
          </div>
515

516
          {/* Detailed state (collapsible) */}
517
          <details className="border-t pt-4">
518
            <summary className="cursor-pointer text-xs font-medium hover:text-foreground">
519
              View Full State Object
520
            </summary>
521
            <div className="mt-4 space-y-3 text-xs">
522
              <div>
523
                <strong>Sorting:</strong>
524
                <pre className="mt-1 overflow-auto rounded bg-muted p-2">
525
                  {JSON.stringify(sorting, null, 2)}
526
                </pre>
527
              </div>
528
              <div>
529
                <strong>Expanded Rows:</strong>
530
                <pre className="mt-1 overflow-auto rounded bg-muted p-2">
531
                  {JSON.stringify(expanded, null, 2)}
532
                </pre>
533
              </div>
534
              <div>
535
                <strong>Pagination:</strong>
536
                <pre className="mt-1 overflow-auto rounded bg-muted p-2">
537
                  {JSON.stringify(pagination, null, 2)}
538
                </pre>
539
              </div>
540
              <div>
541
                <strong>Column Visibility:</strong>
542
                <pre className="mt-1 overflow-auto rounded bg-muted p-2">
543
                  {JSON.stringify(columnVisibility, null, 2)}
544
                </pre>
545
              </div>
546
              <div>
547
                <strong>Column Pinning:</strong>
548
                <pre className="mt-1 overflow-auto rounded bg-muted p-2">
549
                  {JSON.stringify(columnPinning, null, 2)}
550
                </pre>
551
              </div>
552
            </div>
553
          </details>
554
        </CardContent>
555
      </Card>
556
    </div>
557
  )
558
}

	Name	Category	Price	Stock	Status	Brand	Rating	Revenue	Release Date

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

Install the DataTable core and add-ons for this example:

pnpm dlx shadcn@latest add @niko-table/data-table @niko-table/data-table-virtualized @niko-table/data-table-pagination @niko-table/data-table-search-filter @niko-table/data-table-view-menu @niko-table/data-table-column-sort

First time using @niko-table? See the Installation Guide to set up the registry.

For other add-ons or manual copy-paste, see the Installation Guide.

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 { DataTableColumnHeader } from "@/components/niko-table/components/data-table-column-header"
4
import { DataTableColumnTitle } from "@/components/niko-table/components/data-table-column-title"
5
import { DataTableColumnSortMenu } from "@/components/niko-table/components/data-table-column-sort"
6
import type { DataTableColumnDef } from "@/components/niko-table/types"
7

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

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

`<DataTable />` component

Next, we’ll create a virtualized table.

1
"use client"
2

3
import { DataTableRoot } from "@/components/niko-table/core/data-table-root"
4
import { DataTable } from "@/components/niko-table/core/data-table"
5
import {
6
  DataTableVirtualizedHeader,
7
  DataTableVirtualizedBody,
8
  DataTableVirtualizedEmptyBody,
9
  DataTableVirtualizedSkeleton,
10
} from "@/components/niko-table/core/data-table-virtualized-structure"
11
import { DataTableToolbarSection } from "@/components/niko-table/components/data-table-toolbar-section"
12
import { DataTablePagination } from "@/components/niko-table/components/data-table-pagination"
13
import { DataTableSearchFilter } from "@/components/niko-table/components/data-table-search-filter"
14
import { DataTableViewMenu } from "@/components/niko-table/components/data-table-view-menu"
15
import { DataTableColumnHeader } from "@/components/niko-table/components/data-table-column-header"
16
import { DataTableColumnTitle } from "@/components/niko-table/components/data-table-column-title"
17
import { DataTableColumnSortMenu } from "@/components/niko-table/components/data-table-column-sort"
18
import type { DataTableColumnDef } from "@/components/niko-table/types"
19

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

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

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

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

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

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